quarto-tech-memo 0.2.2

A CLI script to convert a markdown note to a polished PDF tech memo using Quarto.

Quarto Tech Memo

See the companion medium article for more background.

This is a quarto extension to create brief technical memos in PDF with the modern and ⚡fast Typst engine (built into Quarto). The memo style provides a professional single-column PDF layout with ample room for sidenotes and small figures in the margin. Inspired by Tufte handout style. The intended use is for brief technical memos and preprints of scientific articles. In addition, a 2-column compact variant and a 3-column A3 poster variants are provided. For reference, a legacy IEEE paper style is also included---using the LaTeX engine. Finally a slide deck variant using the Clean Slide Theme is provided.

The following screenshot shows all variants of the same document. All are formatted from the same source in a few seconds (the IEEE style, with the legacy Latex engine, dominates the rendering time). All generated PDF files are included in the examples folder.

Usage as Python CLI tool

Install the tool, together with all dependencies, with:

pip install quarto-tech-memo

# preferably in a isolated environment with one of:
# pipx install quarto_tech_memo
# uv tool install quarto_tech_memo

Then use the quarto-tech-memo command to convert a markdown file to a polished PDF memo:

quarto-tech-memo you-file.md (--to memo1) (--preview)

Usage within the provided example

Install the dependencies with:

pip install cookiecutter quarto-tech-memo

To render the provided example:

cookiecutter -f gh:gael-close/quarto-tech-memo; cd new-dir;
quarto-tech-memo new-tech-memo.md

For the variants, use one of the flags --to memo2, --to memo3, --to slides, --to poster, or --to ieee

Edit new-tech-memo.md in your favorite editor and re-run the render command or preview changes (one every save) live with:

quarto-tech-memo new-tech-memo.md --preview

Usage in an existing quarto project

To use in an existing Quarto project as an extension, run

# Install the extension (one time only)
quarto add gael-close/quarto-tech-memo

# render with: 
quarto render your-file.md --to memo1-typst

Usage inside a data science project

See this repo https://github.com/gael-close/quarto-tech-paper for usage inside a data science project.

---

Details

• The memo template is based on: https://github.com/kazuyanagimoto/quarto-academic-typst.
• The margin notes are formatted by the marginalia package.
• In markdown, margin notes are should created with the .aside class: see https://quarto.org/docs/authoring/article-layout.html#asides. Note that this should be inline with the surrounding pargaraph (like a footnote).
• Margin notes don't make sense in 2-column style. They are still included inline in the main paragraph nevertheless.
• The slides template is taken from https://typst.app/universe/package/touying-quarto-clean/.
• Custom Lua filters are included for various tweaks.
• To get the ORCID icon, download the fontawesome desktop variant.

Development

Run a test suite with Invoke. This will format the example memo in all variants.

invoke test (--gh) (--no-ieee)

The --gh flag uses the GitHub repo instead of a local copy of the extension. The --no-ieee flag skips the legacy IEEE format which requires a LaTeX installation (install via: quarto install tinytex)

To extract the conversion time for a given format:

invoke conversion-time --format memo1-typst

Lua filters

To run the Lua filter standalone on a test file dev.md:

cd _extensions/meme1/lua-filters
quarto pandoc dev.md -t typst --lua-filter custom.lua

Run as uv tool

Install the tool from the local copy of the repo with:

z quarto-tech-memo
uv tool install . -e

Upload to PyPI

rm -fr dist/*
uv build
uvx uv-publish