With Scitzen you can write documents in a lightweight markup language (think markdown) and generate blog-like websites (think Jekyll) or long-form PDF articles (think LaTeX).
Scitzen has its own markup language, which is a mixture of Markdown, Asciidoc(tor), and LaTeX. It has Markdown like headers and lists, allows for generic blocks like Asciidoctor – though without the syntactic variety – and uses LaTeX style macros (called directives) for inline text.
- Writing static-site-generators is easier than figuring out existing ones.
- Markdown is too limited. Extensions are tool specific.
- Markdown and Asciidoc have too many things I find hard to remember.
- LaTeX has too much ad-hoc styling.
- Writing my own tool, allows me to co-evolve my documents along with my tool.
- Many niche features useful for my use become easy to achieve, this includes:
cross references, includes, aggregates, indexes, support for different outputs (pdf, html), image conversions, running external converters, citation support, automatic download of bib files from online databases, creating slides, ...
The easiest way to run scitzen is to install coursier and run: cs launch --jvm=23 de.rmgk.scitzen:scitzen_3:1.4 -- --help.
You can also install just and scala-cli and run just make-native-image to generate a self-contained binary with much faster startup time.
External tools you might want to install
- tectonic
- node (apt install nodejs)
- node-prismjs (apt install node-prismjs)
- katex (apt install katex)
- pikchr
- graphviz (apt install graphviz)
- d2
- pdftocairo (apt install poppler-utils)
- podman for mermaid (apt install podman)
- warning: the mermaid-cli container image is about 2GB
- warning: the mermaid-cli container image is about 2GB
This “README.md” is actually the HTML output produced by scitzen, just renamed to .md so GitHub renders it as a readme.
The remaining <title> is not stripped by their markdown library for some strange reason.