contents and figures with caption in markdown

[Martin Ueding]

Dear All,

I've been using Sphinx for my personal website for the past years and realized that I more have a blog with posts and few pages and did the conversion to Nikola in the past days. I also took the opportunity to switch to Markdown as I use it with R and Stack Overflow and everywhere else as well.

Previously I used the figure directive with caption a lot. Markdown does have them with the implicit figures extension. Pandoc has it, and I tried to pass it as a Pandoc option. But apparently Nikola uses Python-Markdown, so I installed the figureAltCaption Python module and added it to the extensions. It ran through, but still I do not have implicit figure captions.

MARKDOWN_EXTENSIONS = [                                                        
    'markdown.extensions.fenced_code',                                         
    'markdown.extensions.codehilite',                                          
    'markdown.extensions.extra',                                               
    'figureAltCaption',                                                        
]

Second I have set in my Sphinx theme to have a local table of contents in the sidebar. There are a handful of very long (over 10k words) posts that would benefit from a local table of contents. I saw that the Nikola manual is written in reST and uses the contents directive. I would like to use that also in those posts.

Is there a possibility to use both features with Markdown? I could convert these few posts back to reST and use the contents directive, but for the figures I would need to write HTML manually. I could do that, but I'd prefer to have the directive. Can this be accomplished somehow?

Best regards,

Martin

[Roberto Alsina]

On Sun, May 3, 2020 at 5:18 AM Martin Ueding <m...@martin-ueding.de> wrote:

Dear All,

I've been using Sphinx for my personal website for the past years and realized that I more have a blog with posts and few pages and did the conversion to Nikola in the past days. I also took the opportunity to switch to Markdown as I use it with R and Stack Overflow and everywhere else as well.

Previously I used the figure directive with caption a lot. Markdown does have them with the implicit figures extension. Pandoc has it, and I tried to pass it as a Pandoc option. But apparently Nikola uses Python-Markdown,

Nikola can use Pandoc instead of python-markdown. Look in your conf.py.

 

so I installed the figureAltCaption Python module and added it to the extensions. It ran through, but still I do not have implicit figure captions.

MARKDOWN_EXTENSIONS = [                                                        
    'markdown.extensions.fenced_code',                                         
    'markdown.extensions.codehilite',                                          
    'markdown.extensions.extra',                                               
    'figureAltCaption',                                                        
]

Did you install figureAltCaption? It's not included with Nikola.

 

Second I have set in my Sphinx theme to have a local table of contents in the sidebar. There are a handful of very long (over 10k words) posts that would benefit from a local table of contents. I saw that the Nikola manual is written in reST and uses the contents directive. I would like to use that also in those posts.

There is a toc extension for Python-markdown (and for most other markdowns) https://python-markdown.github.io/extensions/toc/

 

Is there a possibility to use both features with Markdown? I could convert these few posts back to reST and use the contents directive, but for the figures I would need to write HTML manually. I could do that, but I'd prefer to have the directive. Can this be accomplished somehow?

You could use a more 'rst-like' markdown, called myst:https://myst-parser.readthedocs.io/en/latest/index.html

Nikola has a myst plugin I wrote and probably nobody has ever used for real, if you feel experimental: https://plugins.getnikola.com/v8/myst/ 

 

Best regards,

Martin

--
You received this message because you are subscribed to the Google Groups "nikola-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to nikola-discus...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/nikola-discuss/a41b420e-00db-4546-981b-b19c16f98bbb%40googlegroups.com.

[Martin Ueding]

> Did you install figureAltCaption? It's not included with Nikola.

I installed it, and it is working. It is just that it did not work with
hard line wrap in the caption and therefore it failed on the one example
that I checked. I have filed a bug upstream and it works just fine now.

> There is a toc extension for Python-markdown (and for most other markdowns) https://python-markdown.github.io/extensions/toc/

Perfect! That also solves my need.

Thank you very much, now I am super happy with Nikola for my website!

[Everlanes]

Hi,

Second I have set in my Sphinx theme to have a local table of contents in the sidebar. 

I would also like to have a TOC of the current page in the sidebar. I managed to use the Markdown [TOC] extension, but then the TOC is inside the content div.

Is there a way to place the TOC somewhere else inside the HTML DOM using the template?

Did you manage to have the TOC in a sidebar?

Thanks,

  Andreas

[Roberto Alsina]

There is no sidebar in Nikola per se, there are sidebars in some themes.

You can't usually put content in the sidebar.

HOWEVER: hey, it's HTML, you can create the TOC in the content with display: None and copy its innerHTML into a DIV in the sidebar using JS.