Skip to content

Commit

Permalink
Add Pandoc support, refactor external helpers
Browse files Browse the repository at this point in the history
Recognize the Pandoc format under the file extension .pandoc or .pdc,
and shell out to pandoc as an external helper to format Pandoc content.

Refactor out repeated code with external helpers. Change the error
output formatting. I did not see any of the external helpers print the
string "<input>" to represent stdin as a file; just prepending the file
name to error output is more general and doesn't sacrifice that much in
terms of readability.

Closes #234
  • Loading branch information
betaveros authored and bep committed Nov 30, 2017
1 parent c7c3ee7 commit 7d8c783
Showing 1 changed file with 10 additions and 2 deletions.
12 changes: 10 additions & 2 deletions content/content-management/formats.md
Expand Up @@ -6,7 +6,7 @@ date: 2017-01-10
publishdate: 2017-01-10 publishdate: 2017-01-10
lastmod: 2017-04-06 lastmod: 2017-04-06
categories: [content management] categories: [content management]
keywords: [markdown,asciidoc,mmark,content format] keywords: [markdown,asciidoc,mmark,pandoc,content format]
menu: menu:
docs: docs:
parent: "content-management" parent: "content-management"
Expand Down Expand Up @@ -195,12 +195,19 @@ With this setup, everything is in place for a natural usage of MathJax on pages


## Additional Formats Through External Helpers ## Additional Formats Through External Helpers


Hugo has new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].) Hugo has a new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [pandoc]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].)


For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](http://asciidoctor.org/docs/install-toolchain/)). For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](http://asciidoctor.org/docs/install-toolchain/)).


To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files. To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files.


Hugo passes reasonable default arguments to these external helpers by default:

- `asciidoc`: `--no-header-footer --safe -`
- `asciidoctor`: `--no-header-footer --safe --trace -`
- `rst2html`: `--leave-comments --initial-header-level=2`
- `pandoc`: `--mathjax`

{{% warning "Performance of External Helpers" %}} {{% warning "Performance of External Helpers" %}}
Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
{{% /warning %}} {{% /warning %}}
Expand Down Expand Up @@ -235,6 +242,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are
[mmark]: https://github.com/miekg/mmark [mmark]: https://github.com/miekg/mmark
[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax [mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax
[org]: http://orgmode.org/ [org]: http://orgmode.org/
[pandoc]: http://www.pandoc.org/
[Pygments]: http://pygments.org/ [Pygments]: http://pygments.org/
[rest]: http://docutils.sourceforge.net/rst.html [rest]: http://docutils.sourceforge.net/rst.html
[sc]: /content-management/shortcodes/ [sc]: /content-management/shortcodes/
Expand Down

0 comments on commit 7d8c783

Please sign in to comment.