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

• [x] includes of other md files ([include foo.md], ![][foo.md])
• [x] cite author formatting (> -- [@foo])
• [x] renders ok-ish in commonmark renderers
• [x] produces readable latex
  • worst case: fall back to latex if heradoc fails
• [x] generate links for sections (non-alphanumerics replaced with -, all lowercase)
• [x] Footnotes (currently the footnote is on the page where the footnote definition is placed, not its first reference)
• [x] biber support: [@foo] references biber
• [x] 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
• [x] Table of Contents: [TOC], ![][//TOC]
• [x] Bibliography: [bibliography], ![][//bibliography]
• [x] List of Listings: [listoflistings], ![][//listoflistings]
• [x] List of Tables: [listoftables], ![][//listoftables]
• [x] List of Figures: [listoffigures], ![][//listoffigures]
• [x] ```graphviz: Rendered graphviz dot format (using dot cli)
• [x] inline latex math mode (`$ foo)
• [x] equation without number (```$$\nfoo\n```)
• [x] equation with number (```$$$\nfoo\n```)
• [x] hrule
• [x] pagebreak / newpage (\n===\n)
• [x] 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])
• [x] [appendix]: sets all correct formatting for appendix, should be used before the heading

• [x] 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")

• [x] unified item attributes for code blocks / equations / numbered equations / tables
  • [x] label
  • [x] figure / nofigure / figure=true / figure=false
  • [x] caption
  • [x] scale / width / height for image / graphviz / ...
• [x] 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

• [x] output (file / stdout)
• [x] out-type (tex, pdf, …)
• [x] papersize
• [x] documentclass
• [x] geometry
• [x] header includes
• [x] pdf metadata
  • [ ] compare with pandoc
• [x] figures (true / false): puts every listing / image / … inside figures
• [x] 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

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

Backend

• latex backend
  • [x] article (scrartcl)
  • [x] thesis (scrbook)
  • [x] 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:

• [x] pulldown-cmark