Skip to content

Outputs

Every output is made by pandoc, which runs in the tool container.

outputs:
  docx: {template: templates/Template.docx}
  pdf: {toc: true}                  # XeLaTeX, with the built-in template unless `template` names a .tex file
  html: {template: styles/doc.css}  # one self-contained file; `template` is the stylesheet
  pptx: {split_level: 2, template: templates/Slides.pptx}

Word

Pandoc writes the document with the template as its reference document, so the template’s styles decide how everything looks (Heading 1, Body Text, First Paragraph, Compact, Block Text, Source Code, Table, Image Caption and so on). A template can be .docx or .dotx. Without one, a built-in reference document is used, which defines the callout box styles.

  • Merging: when a template is set, the result is merged into it. The body goes where [[INSERTCONTENT]] stands, or at the end if there is no marker. [[LANDSCAPE]], [[PORTRAIT]], [[STYLE:Name]] and [[CAPTION:Figure]] lines are applied afterwards.
  • Placeholders: Replace-with-Title, -Author, -Version, -Document-Number, -Date, -Description and -Classification are filled in the template body, tables, headers and footers. placeholder_prefix (default Replace-with-) and marker (default [[INSERTCONTENT]]) can be changed. A placeholder the document has no value for is emptied with a warning, and one that no property can fill (Replace-with-Mystery) is left and named in a warning.
  • Heading numbers: a template can number its heading styles (a Heading 1 with list numbering). The numbers written in the headings would then show twice, so py-doc leaves them out: ## 2.1 Design becomes ## Design, numbered by Word. heading_numbers: strip or keep decides it for any template. See Heading numbers.
  • Contents list: docx: {toc: true} adds a table of contents to the depth of toc_depth (front matter). Word fills in the page numbers when the file is opened and asks to update fields.
  • Document properties (title, author, subject, keywords, category, comments) are capped at Word’s 255 characters, with a warning when a value is cut.
  • Code is highlighted with the built-in theme.
  • A missing template is an error, unless allow_missing_template: true. Pandoc’s own warnings are shown as warnings.

PowerPoint

Slides start at headings up to split_level (--split-level, default 2) and at ::: {.pagebreak} lines. The title and author in the front matter make the title slide. Pandoc chooses layouts by their standard names (Title Slide, Title and Content, Section Header, Two Content, Comparison), so a template must start from pandoc --print-default-data-file reference.pptx and be edited in PowerPoint. A template that gives an empty deck is reported with that hint.

  • Speaker notes: <!-- notes: text -->, or a ::: notes block for more than one paragraph.
  • Columns: a :::: columns block with two ::: column blocks uses the Two Content layout.
  • Diagrams and pictures sit on the slide on their own, with the [[CAPTION:Figure]] text under them.
  • Footer: footer: "{title} v{version}" fills the footer placeholder of every slide (a layout without one is reported), and {{VERSION}} in a template shape is replaced by the version.
  • Long slides: a slide with more than 16 lines gets a warning, because nothing is shrunk silently.
  • Fonts embedded in a template are kept.

PDF and HTML

  • PDF is written by XeLaTeX with a built-in template that has a title page, or the .tex file named by template. toc is on by default. Callouts are coloured boxes, maths is typeset, and task lists keep their boxes.
  • HTML is one self-contained file with pictures embedded. template is the stylesheet (py-doc’s own by default), toc: true adds a contents list, and maths is MathML.

HTML deck

An HTML deck is the same slides as one self-contained web page, for a screen, the web or a PDF handout. It needs no PowerPoint. Build it with py-doc slides talk.md -f html, or with an html output that has deck: true:

documents:
  deck:
    sources: [docs/deck/slides.md]
    outputs:
      pptx: {split_level: 2, footer: "{title} v{version}"}
      html: {deck: true, pdf: true}       # build/deck.html, and build/deck.pdf

It splits the slides as the PowerPoint deck does, and takes the same speaker notes, columns and page breaks. An HTML deck that sets no split_level or footer takes those of the document’s pptx output, so the two decks match.

Option Default What it sets
deck false true makes the html output an HTML deck
split_level, footer Those of pptx, else 2 and none As for PowerPoint. The footer and the slide number are at the bottom of each slide
aspect 16:9 16:9 or 4:3
theme default A poster theme, default, dark or print, or a theme file. See Themes
embed_fonts false true puts the theme’s web fonts inside the page
pdf false true also prints the deck to a PDF beside it, one slide a page, with the tool container’s Chromium

Poster blocks, such as cards, chart and steps, are drawn on the slide as they are on a poster, with no picture step. Diagrams are SVG, and maths is MathML. The page scales each slide to the window. The keys are listed in Present an HTML deck.

A slide of more than 16 lines gets a warning, as in PowerPoint. The page also marks a slide whose content is taller or wider than the slide with a red edge, and names it in the browser’s console. With pdf, the build names those slides in a warning too. Nothing is shrunk to fit.

Heading numbers

Write headings with or without their section numbers. Where the output numbers its headings itself, py-doc takes the written numbers off, so a section is never numbered twice.

outputs:
  docx: {template: templates/Numbered.docx}   # auto: the template numbers its headings, so 2.1 is left out
  pdf: {number_sections: true}                # pandoc numbers the sections, and 2.1 is left out
  html: {heading_numbers: keep}               # the numbers stay as written
heading_numbers Effect
auto (default) Strip in Word when the template’s Heading 1 style is numbered, and in PDF and HTML with number_sections: true. Keep otherwise
strip Always take the written numbers off
keep Always leave the headings as written

These are taken off: 2.1, 2.1.3, 3. and A.1, with or without a final full stop. A bare number such as 1 Introduction comes off only when every heading of that level starts with one and they count 1, 2, 3 in order, so 2024 roadmap stays. A heading that is only a number stays as written. The log says when numbers were taken off.

Templates

py-doc template check Template.docx reports what the template lacks for the pandoc pipeline. .docx, .dotx, .pptx and .potx are accepted.

py-doc template check templates/sensor.docx --strict
py-doc template check templates/datasheet.docx --strict --prefix "@@" --marker "<<BODY>>"
py-doc template show templates/sensor.docx         # the styles, or the layouts of a deck
py-doc template diff A.docx B.docx                 # styles or layouts missing from one, or defined differently
py-doc template usage File.docx                    # how often a Word file uses each style

A FAIL exits with status 1: a style of the wrong type, bold body text, or a deck without the Title Slide or Title and Content layout. A WARN, such as a style pandoc will take from its own defaults, exits with 1 only with --strict. -v adds INFO. diff exits with 1 when the templates differ. A build runs the check, logs the failures and carries on. py-doc init --templates writes pandoc’s own reference documents to start from.