Introduction

Lamarkdown is a command-line document preparation system based on Python-Markdown. It attempts to address similar use cases to LaTeX, but using the Markdown and HTML formats. It is not directly intended to build static websites, though its extensions can be reused in MkDocs (or in other applications based on Python-Markdown).

Take the Lamarkdown tour to get a first impression.

1. Requirements and Installation

Lamarkdown depends on Python 3.8+. To install via pip:

$ pip install lamarkdown

There are optional dependencies that you’ll need to install separately, to make use of certain Lamarkdown features.

  • For embedding LaTeX diagramming code, you need a Latex distribution (e.g., TeX Live), and a PDF-to-SVG conversion tool. (Lamarkdown can embed LaTeX mathematical expressions without a LaTeX distribution, and does not require LaTeX for any part of its core operation.)

  • Similarly, to embed the output of Graphviz, Matplotlib, R (for plotting), or PlantUML, you will also need to install these yourself.

2. Basic Usage

To compile mydocument.md into mydocument.html, run:

$ lamd mydocument.md

To enable the live-update mode, use -l/--live:

$ lamd -l mydocument.md

This will launch a local web-server and a web-browser, and will keep mydocument.html in sync with any changes made to mydocument.md, until you press Ctrl+C in the terminal.

For detailed usage, Lamarkdown’s documentation is structured as follows:

  • The Tour gives a glimpse of Lamarkdown’s key features, to give you an overall sense of what’s possible.
  • The Core Functionality section describes the essential workings of Lamarkdown, including build files (at a conceptual level), directives, variants, allow_exec, resource processing and caching.
  • The Extensions section covers add-on Markdown functionality. Extensions (often) make changes to the Markdown syntax, to introduce additional capabilities.
  • The Build Modules section covers pre-designed bundles of reusable configuration.
  • The Build File API section specifies all programmatic Lamarkdown functionality accessible to a build file.

3. Why Lamarkdown?

Lamarkdown addresses a need for creating accessible, portable (and optionally scriptable) documents, using a maximally-readable plain-text source format, and a programmable build process.

3.1. Word Processors, LaTeX and PDFs

WYSIWYG word processors (Word, LibreOffice, Google Docs and others) are perhaps the most-used document-preparation systems. These are highly successful applications, but the endurance of LaTeX, despite its learning curve, demonstrates a long-standing demand for plain-text document creation as well.

LaTeX (and TeX in general) offers transparency. The PDF files generated by pdftex, xetex and luatex depend only on the text you explicitly write. There are no invisible elements or hidden dimensions to a LaTeX document; all factors affecting the output are plainly visible as text. You can edit a LaTeX document with any of hundreds of different editors, and have no concern that some hidden property might change beyond your control (leaving the document unpredictably reformatted or corrupted). LaTeX also encourages greater focus on pure content, while the compiler makes sensible stylistic decisions automatically. Both these things promote consistency and (subject to a learning curve) productivity.

TeX/LaTeX is extensible, but also has distinct weaknesses:

  • It was designed to produce static, paginated, printable documents, whereas documents today are rarely printed. It was not designed to produce re-flowable documents that can be presented at different sizes, or documents accessible to vision-impared people. The Portable Document Format (PDF) struggles to address these issues itself, and is difficult to work with programmatically.

  • LaTeX code is relatively verbose, which can limit its productivity benefits.

3.2. Markdown and HTML

The Markdown format shares many of LaTeX’s advantages, but was designed for purely electronic communication. It is conventionally compiled into HTML, a universally-supported, re-flowable format that retains structural semantics needed for screen readers. Markdown is one of a number of plain-text formats to do this, but is notable for its minimalistic syntax and widespread use. (HTML itself can be written manually, but being even more verbose than LaTeX, and without any “compile-time” extensibility, this is difficult to do productively.)

Markdown is commonly used to build static websites. Various tools exist to convert a collection of .md (Markdown) files into a collection of .html files, to be uploaded to a webserver. For instance, this site was generated from Markdown files using MkDocs, which uses the Python-Markdown library.

However, this is a different use case from the preparation of individual, standalone documents, as done through LaTeX. Markdown, as a format, is an attractive choice for both use cases, but standalone document preparation has certain extra or different requirements:

  • Documents should be viewable without any webserver infrastructure (or external services), since this is not feasible or sustainable for documents in general. Even if infrastructure or services can be set up, they may not have the required longevity.

  • Documents should be self-contained (like PDFs in general), so they can be stored and exchanged without risk of losing resources “contained” within them.

  • While we’d like the option for documents to be scriptable, they should ideally not depend on scripting, and if possible contain no executable code at all. Scripting is subject to ongoing change. API features may be deprecated and abandoned in the future, for security, efficiency or maintenance reasons, under the assumption that affected websites are being actively maintained, and can simply adapt. Such future changes could render a script-dependent document suddenly unviewable, perhaps without anyone noticing for some time until the document is needed.

  • Document preparation benefits from specific features not necessarily present in static site generators:

    • Citation and reference formatting;
    • Automatic numbering of sections, figures, tables, etc., and cross-referencing using such numbers;
    • Captioning of figures, tables, etc.;
    • Creation of graphical content within the document;
    • Creation of arbitrarily-complex tables;
    • Creation of alternate document versions from the same source.