Heradoc is a markdown to LaTeX converter. It is a very biased partial reimplementation of pandoc with a pinch of hackmd.

Building

Rust needs to be installed. To find out how to install rust, visit https://rustup.rs and follow all of the instructions.

Linux / WSL

The below doesn't work for WSL, but it's a beginning. If anyone wants to try out building heradoc for WSL, feel free to open a PR.

For ubuntu, ensure that you are using its latest version, to ensure that you have the newest versions of all packages. To do that, run sudo apt update && sudo apt upgrade && do-release-upgrade.

On ubuntu, install pkg-config, libssl-dev, libpango1.0-dev, libxml2-dev, libcairo2-dev, texlive and graphviz. On arch, install base-devel, openssl, pango, libxml2, cairo, texlive-bin, texlive-core, texlive-latexextra, texlive-bibtexextra, biber and texlive-science. For other distributions, those packages may have different names.

Windows

Install the following programs:

• texlive: Download the install-tl-windows.exe from https://www.tug.org/texlive/acquire-netinstall.html
  • if downloading with that installer is incredibly slow / takes incredibly long, abort installation and try using a different mirror
  • other latex implementations might also work
• graphviz:
  • during installation, select Add Graphviz to the system PATH for all users
  • download and execute the installer from https://www2.graphviz.org/Packages/stable/windows/10/cmake/Release/x64/
  • make sure Graphviz is installed by running dot.exe from a fresh cmd
  • if the error message There is no layout engine support for "dot" appears:
    • open cmd as administrator (search for cmd in the start menu, right-click and select "Run as Administrator")
    • run dot -c
• in cmd, navigate to the folder into which you cloned this heradoc repository and run cargo install --path . (note the dot) build and install heradoc for the current user
• to convert a file from markdown to pdf, run heradoc file.md in cmd

Features

• includes of other md files ([include foo.md], ![][foo.md])
• cite author formatting (> -- [@foo])
• renders ok-ish in commonmark renderers
• produces readable latex
  • worst case: fall back to latex if heradoc fails
• generate links for sections (non-alphanumerics replaced with -, all lowercase)
• Footnotes (currently the footnote is on the page where the footnote definition is placed, not its first reference)
• biber support: [@foo] references biber
• inline latex: \ \LaTeX in text, ```inlinelatex\n\LaTeX\n``` as block
  • still render markdown between \begin and \end etc, which pandoc doesn't
  • not if HTML as backend
• Table of Contents: [TOC], ![][//TOC]
• Bibliography: [bibliography], ![][//bibliography]
• List of Listings: [listoflistings], ![][//listoflistings]
• List of Tables: [listoftables], ![][//listoftables]
• List of Figures: [listoffigures], ![][//listoffigures]
• ```graphviz: Rendered graphviz dot format (using dot cli)
• inline latex math mode ( `$ foo)
• equation without number (```$$\nfoo\n```)
• equation with number (```$$$\nfoo\n```)
• hrule
• pagebreak / newpage (\n===\n)
• unicode support (for common symbols, translate into latex math equivalents, e.g. →, basically neo layer 6 :D )
  • typographic replacements (e.g. (c), (r), (tm))
  • code-blocks with inline unicode / math-mode (\begin{lstlisting}[mathescape=true])
• [appendix]: sets all correct formatting for appendix, should be used before the heading
• unified labels (#16)
  • Header labels:
    • {#my-label}\n\n# Header: "prefix"-style
    • # Header {#my-label}: "inline"-style
    • # Header: autogenerated (#header)
      • [^a-zA-Z0-9-_ ] removed, [ ] replaced with -
  • Code (graphviz, equation, …) / Table / Image labels ("prefix-style"):
    • must start with { and end with }
    • must be either its own markdown paragraph (empty line before and in some cases empty line after) or at the start of a paragraph followed by a SoftBreak (empty line before and line break after)
    • may be indented (will be trimmed)

    {#my-label}
    ```rust
    fn main() {}
    ```

    • Tables require empty line, otherwise it isn't a valid table

    {#my-label}
    
    Head 1 | Head 2
    --- | :-:
    Cell 1 | Cell 2

  • Code (graphviz, equation, …) has additional style for easier compatibility with other markdown parsers

    ```rust,#my-label
    fn main() {}
    ```
    

  • Images (label must start a paragraph and be followed by a line break with the image directly after)

    {#fancy-image}
    ![alt-text](link "title")

• unified item attributes for code blocks / equations / numbered equations / tables
  • label
  • figure / nofigure / figure=true / figure=false
  • caption
  • scale / width / height for image / graphviz / ...
• tasklist: - [ ] foo
• tables: merge columns
• tables: merge rows
• tables: merge columns and rows (e.g. 3x3 field)
• comments
• ```sequence
• ```flow
• ```gnuplot
• ```mermaid
• ```abc
• citation style (.cs)
• label-list: * `label`: Description (escape hatch with double-space after list item dot)
• description-list: * **description**: Description (escape hatch with double-space after list item dot)
• includes of files other than images / md
• alert area??? (success, info, warning, danger)
• superscript (foo^bar^)
• subscript (foo~bar~)

Config Options

• output (file / stdout)
• out-type (tex, pdf, …)
• papersize
• documentclass
• geometry
• header includes
• pdf metadata
  • compare with pandoc
• figures (true / false): puts every listing / image / … inside figures
• oneside (true / false)
• itemizespacing
• use minted instead of lstlistings
• lstset
• graphicspath (probably not needed due to resolve)
• cleveref options
• let footnotes appear where they are first used vs where they are declared
• make softbreaks (line breaks) hard brakes (line ends with 2 spaces)
• typed config options per type (instead of strings) where appropriate

Cli

• heradoc -o bar.pdf bar.md
• configuration file
• configuration directly in .md file similar to pandoc, but better :)
  • pandoc header renders bad in other markdown renderers
  • ```heradoc
  • ```config
• heradoc bar.md (short for heradoc -o bar.pdf bar.md)
• every cli option must be configurable in the header (except -o and similar)
• cli overrides header overrides config-file overrides defaults

Backend

• latex backend
  • article (scrartcl)
  • thesis (scrbook)
  • report (scrreprt)
  • beamer
• HTML backend
  • get rid of latex altogether
  • book
  • slides
• Generation via file templates
  • separate templates for headers and body
  • one template which headers and body get rendered into
  • http://www.arewewebyet.org/topics/templating/

Frontend:

• pulldown-cmark