Hugo: Add support for parsing citations and Jupyter notebooks via Pandoc and/or Goldmark extension

[gcushen]

Problems

1. Currently, the markup option is only available on a per page basis - how can we give users the option to
   
   
   
   1. change the default parser to another parser such as Pandoc in order to parse technical content (if say a user prefer to trade off speed for functionality)
   
   
   2. configure each parser's options in config.toml
   
   
2. Hugo's Goldmark and Blackfriday don't currently support citations using the popular Cite-Proc standard
   
   
   
   1. What can we do to empower academics and technical content writers to write citations/bibliographies?
   
   
3. Currently Jupyter notebooks cannot be parsed by Hugo into Markdown
   
   
   
   1. Empower data scientists, analysts, and academics by enabling Pandoc to parse Jupyter notebooks (.ipynb) into Markdown
   
   
4. Different parsers render things like ToC differently - how can we handle this?

Potential solution

Implementation stories:

• [x] Enable choosing the default markup parser for the entire site via a markup option in config.toml (implemented in #5963)
• [ ] Enable Pandoc and its Cite-Proc addon (or alternatively, a Goldmark extension) to parse both an entire site and specific Markdown (.md) files (based on file type and/or front matter param) so that technical content including citations can be rendered correctly
• [ ] Enable Pandoc to parse Jupyter notebooks (.ipynb) into Markdown
• [ ] Add site and page variables named .Markup so that we can perform different actions in a theme depending on the Markup of that site or page (to handle things like ToC being rendered differently)

[nancym]

If this happens, which I would like, please make markup a table so those of us who use multiple markup languages have better control. For example:

markup:
  mmark:
    - .mmark
    - .md
    - .mdown
    - .markdown
  asciidoc:
    - .ad
    - .adoc
    - .asciidoc
  markup-lang:
    - .extension1
    - .extension2

Any markup language not specified in this config-file table would use Hugo's defaults, which I've written about at https://www.ii.com/hugo-markup-languages/

[gcushen]

I agree with the above comment - in particular, this flexibility of defining Markup for the site would enable Pandoc to parse Jupyter notebooks (.ipynb) into Markdown which would be extremely valuable for data scientists/analysts!

[gcushen]

Also, please 🙏 add site and page variables named .Markup so that we can perform different actions in a theme depending on the Markup.

For example, this would enable a theme to generate a TOC using our own Go Templating functionality for Mmark (which doesn't support automatic TOC generation) whereas a theme could automatically use the built-in TOC function if a page's Markup is BlackFriday.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[gcushen]

This issue is still relevant. In fact, it's currently the 3rd most upvoted feature request for Hugo.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[danmackinlay]

So that this issue is something other than people fending off the stalebot, perhaps we could split it into two: one for jupyter notebook support and one for pandoc-citeproc-like citations, each of which is more attainable in a pull-request?

[alexandrevicenzi]

I made a shortcode that parses ipynb into markdown, not the best way to solve the problem, but at least I can add a jupyter notebook as part of an article, or even add a dozen of notebooks.

It works like this: {{<jupyter src="/path/to/jupyter/notebook.ipynb" >}}

Does this approach sound interesting?