Pandoc Document Converter

Terminal

Published

February 19, 2016

Modified

January 21, 2023

pandoc generates documents from various input and output formats.

Therefore it is used to convert between document formats as well.

Input, output and document formats…

…input document specified with --from…
- …supports multiple Markdown variants
- …defaults to -f markdown for Pandoc’s Markdown
…format defined with option --to…defaults to html

# list all supported markdown variants
pandoc --list-input-formats | grep markdown

…files path defined with option --output
- …--standalone include header & footer for a given format
- …--css adds CSS from a file to an HTML document template
--table-of-contents to generate a table of content

Configuration

Instead of using command-line options & arguments…

…use a defaults file …in the form of a YAML file
…option -d,--defaults= …path to file, for example pandox.yaml
${.} variable
- …resolve to the directory containing the defaults file itself
- …only works in fields that expect file paths
# …to prefix comments

Example…

from: markdown+yaml_metadata_block
standalone: true
self-contained: true
toc: true
template: ${.}/_templates/page.html 
css:
  - ${.}/_templates/normalize.css
  - ${.}/_templates/main.css
resource-path:
  - .
  - ${.}/images

Templates

Option --template for custom template documents…

…pandoc -D $format to print the default template
…templates contain variables set
- …default variables
- …with option -V,--variable
- …YAML metadata block…
  - …within the file header
  - …dedicated file with option --metadata-file
  - ..defaults file metadata: or metadata-file:

Headers & References

ATX-style heading…

…+auto_identifiers extension
- {#<label>} specific label for a header
- {-} will not be numbered
…+implicit_header_references extension
- …behaves as if reference links have been defined for each heading
- [heading] to reference an existing # heading

# A level-one heading {#level-1}

## A level-two heading {-}

### A level-three heading

...[level one](#level-1)

[A level-three heading]

pandoc-secnos filter…

…for numbering section references
Source Code Repository, GitHub
- https://github.com/tomduck/pandoc-secnos
Enables…
- …cross-referencing syntax
- {@sec:label} prefix for a unique reference
- +@sec:label adds reference number mid sentence

Text Style

Use the common Markdown inline formatting for emphasis. Pandoc support in addition…

with*emphasis
with_emphasis
strong emphasis
strong emphasis
feasible, not feasable
~~deleted text~~
H₂O is a liquid. 2¹⁰ is 1024.

Markdown…

_with\*emphasis_
*with_emphasis*
__strong emphasis__
**strong emphasis**
feas*ible*, not feas*able*
~~deleted text~~
H~2~O is a liquid.  2^10^ is 1024.

…HTML markup…

<em>with*emphasis<em>
<em>with_emphasis<em>
<strong>strong emphasis</strong>
<strong>strong emphasis</strong>
"feas"<em>ible</em>, not "feas"<em>able</em>
<del>deleted text</del>
"H"<sub>2</sub>"O is a liquid.  2<sup>10</sup>" is 1024"

`` Element

Mark relevant text using the  HTML element…

…requires bracketed_spans extension (enabled by default)
…append {.mark} to a text enclosed with [...]

Text within a mark-element

Markdown…

[Text within a mark-element]{.mark}

…HTML markup…

<mark>Text within a mark-element]</mark>

…style sheet…

mark {
  background-color: rgba(255, 238, 0, 0.38);
  padding:0.25rem;
}

`` Element

Syntax highlight text (for example colors) with  elements…

Text in light
Text in medium
Text in dark

Markdown…

[Text in light]{.light}
[Text in medium]{.medium}
[Text in dark]{.dark}

…HTML markup…

<span class="light">Text in light</span>
<span class="medium">Text in medium</span>
<span class="dark">Text in dark</span>

…style sheet…

span.light {
  color: rgba(232, 232, 232, 1);
}
span.medium {
  color: rgba(204, 204, 204, 1);
}
span.dark {
  color: rgba(114, 114, 114, 1);
}

Code Fragments

`<code>` Element

TODO

`<pre>` Element

Fenced code blocks with backticks…

…enables syntax high-lighting for code blocks
…pandoc --list-highlight-languages lists supported languages

Append language identifier to the backticks…

puts "Hello World"

Markdown…

```ruby
puts "Hello World"
```

Optional attributes in curly braces {...}…

…#label to specify a reference identifier label
….syntax to for a specific language syntax to highlight
….numberLines to enable line numbering

function _error() {
        echo 1>&2 "$SCRIPT error: $@"
        exit 1
}

Markdown…

```{#label .sh .numberLines}
function _error() {
        echo 1>&2 "$SCRIPT error: $@"
        exit 1
}
```

Extensions

Extensions…

…pandoc --list-extensions to list extensions enabled by default
…configure with --from markdown[+-]...
- …enable +EXTENSION
- …disable -EXTENSION

Filters

Lua filters…

Manipulate the Pandoc abstract syntax tree (AST)…
…between parsing input and writing output
…option --lua-filter= to pass a Lua filter

--- title: Pandoc Document Converter categories: - Terminal date: 2016/02/19 date-modified: 2023/01/21 --- `pandoc` generates documents from various input and output formats. Therefore it is used to convert between document formats as well. Input, output and document formats... - ...input document specified with `--from`... - ...supports multiple [Markdown variants](https://pandoc.org/MANUAL.html#markdown-variants) - ...defaults to `-f markdown` for [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) - ...format defined with option `--to`...defaults to `html` ```sh # list all supported markdown variants pandoc --list-input-formats | grep markdown ``` - ...files path defined with option `--output` - ...`--standalone` include header & footer for a given format - ...`--css` adds CSS from a file to an HTML document template - `--table-of-contents` to generate a table of content ## Configuration Instead of using command-line options & arguments... * ...use a [defaults file](https://pandoc.org/MANUAL.html#defaults-files) ...in the form of a YAML file * ...option `-d`,`--defaults=` ...path to file, for example `pandox.yaml` * `${.}` variable * ...resolve to the directory containing the defaults file itself * ...only works in fields that expect file paths * `#` ...to prefix comments Example... ```yaml from: markdown+yaml_metadata_block standalone: true self-contained: true toc: true template: ${.}/_templates/page.html css: - ${.}/_templates/normalize.css - ${.}/_templates/main.css resource-path: - . - ${.}/images ``` ## Templates Option `--template` for [custom template](https://pandoc.org/MANUAL.html#templates) documents... * ...`pandoc -D $format` to print the default template * ...templates contain variables set * ...[default variables](https://pandoc.org/MANUAL.html#variables) * ...with option `-V`,`--variable` * ...YAML metadata block... * ...within the file header * ...dedicated file with option `--metadata-file` * ..defaults file `metadata:` or `metadata-file:` ## Headers & References ATX-style heading... - ...`+auto_identifiers` extension - `{#<label>}` specific label for a header - `{-}` will not be numbered - ...`+implicit_header_references` extension - ...behaves as if reference links have been defined for each heading - `[heading]` to reference an existing `# heading` ```md # A level-one heading {#level-1} ## A level-two heading {-} ### A level-three heading ...[level one](#level-1) [A level-three heading] ``` `pandoc-secnos` filter... - ...for numbering section references - Source Code Repository, GitHub - <https://github.com/tomduck/pandoc-secnos> - Enables... - ...cross-referencing syntax - `{@sec:label}` prefix for a unique reference - `+@sec:label` adds reference number mid sentence ## Text Style Use the common Markdown inline formatting for emphasis. Pandoc support in addition... _with\*emphasis_ *with_emphasis* __strong emphasis__ **strong emphasis** feas*ible*, not feas*able* ~~deleted text~~ H~2~O is a liquid. 2^10^ is 1024. Markdown... ```md _with\*emphasis_ *with_emphasis* __strong emphasis__ **strong emphasis** feas*ible*, not feas*able* ~~deleted text~~ H~2~O is a liquid. 2^10^ is 1024. ``` ...HTML markup... ```html with*emphasis with_emphasis strong emphasis strong emphasis "feas"ible, not "feas"able <del>deleted text</del> "H"2"O is a liquid. 210" is 1024" ``` ### `` Element Mark relevant text using the `` HTML element... * ...requires `bracketed_spans` extension (enabled by default) * ...append `{.mark}` to a text enclosed with `[...]` [Text within a mark-element]{.mark} Markdown... ```md [Text within a mark-element]{.mark} ``` ...HTML markup... ```html Text within a mark-element] ``` ...style sheet... ```css mark { background-color: rgba(255, 238, 0, 0.38); padding:0.25rem; } ``` ### `` Element Syntax highlight text (for example colors) with `` elements... [Text in light]{.light} [Text in medium]{.medium} [Text in dark]{.dark} Markdown... ```md [Text in light]{.light} [Text in medium]{.medium} [Text in dark]{.dark} ``` ...HTML markup... ```html Text in light Text in medium Text in dark ``` ...style sheet... ```css span.light { color: rgba(232, 232, 232, 1); } span.medium { color: rgba(204, 204, 204, 1); } span.dark { color: rgba(114, 114, 114, 1); } ``` ## Code Fragments ### `<code>` Element TODO ### `<pre>` Element **Fenced code** blocks with backticks... - ...enables [syntax high-lighting](https://pandoc.org/MANUAL.html#syntax-highlighting) for code blocks - ...`pandoc --list-highlight-languages` lists supported languages Append language identifier to the backticks... ```ruby puts "Hello World" ``` Markdown... ``````txt ```ruby puts "Hello World" ``` `````` **Optional attributes** in curly braces `{...}`... - ...`#label` to specify a reference identifier `label` - ...`.syntax` to for a specific language `syntax` to highlight - ...`.numberLines` to enable line numbering ```{#label .sh .numberLines} function _error() { echo 1>&2 "$SCRIPT error: $@" exit 1 } ``` Markdown... ``````txt ```{#label .sh .numberLines} function _error() { echo 1>&2 "$SCRIPT error: $@" exit 1 } ``` `````` ## Extensions [Extensions](https://pandoc.org/MANUAL.html#extensions)... - ...`pandoc --list-extensions` to list extensions enabled by default - ...configure with `--from markdown[+-]...` - ...enable `+EXTENSION` - ...disable `-EXTENSION` ## Filters Lua [filters](https://pandoc.org/lua-filters.html)... * Manipulate the Pandoc abstract syntax tree (AST)... * ...between parsing input and writing output * ...option `--lua-filter=` to pass a Lua filter

Pandoc Document Converter

Configuration

Templates

Headers & References

Text Style

`<mark>` Element

`<span>` Element

Code Fragments

`<code>` Element

`<pre>` Element

Extensions

Filters

Configuration

Templates

Headers & References

Text Style

<mark> Element

<span> Element

Code Fragments

<code> Element

<pre> Element

Extensions

Filters

`<mark>` Element

`<span>` Element

`<code>` Element

`<pre>` Element