This chapter will provide and analysis
of the data format Markdown
and the Markdown-based publishing system Quarto.
This project mainly involves navigating in and altering data structures.
Main data structures are the document formats Markdown, HTML and PDF,
and the abstract data language RDF,
serialised as RDFa (embedded in HTML) and PDF (embedded in PDF).
Markdown
Markdown is "probably the most popular markup language today"
[@Rapp2023, p. 42].
It was originally defined by @Gruber2004
as a superset of HTML,
improving readability and ease of writing
by adding email-style markup
for common content structure like headers, emphasis, lists and hyperlinks.
A core principle of Markdown is readability:
A Markdown-formatted document should be publishable as-is,
as plain text,
without looking like it’s been marked up
with tags or formatting instructions..
[@Gruber2004, section "Philosophy"].
Many dialects of Markdown have evolved,
some tightening the language for parsing efficiency and disambiguation,
some extending to cover additional structures
and some including support for a YAML or TOML metadata header section.
Markdown as originally designed is a source format to produce HTML.
If using only Markdown-defined markup, avoiding HTML tags,
the text is however reliably translatable also to other formats.
Pandoc is a tool that can convert texts in Markdown dialects
into many document formats including HTML and (via LaTeX) PDF,
applying visual style and positioning throught templates.
Such document workflows,
including minimal structural markup as part of the creative writing,
applying visual layout as an automated templating process
tied to a target document format,
has been further streamlined for academic texts
in the Quarto document publishing system.
Markdown is a text markup language
with an emphasis on being easy for humans to read
[@Gruber2004].
Compared to word processors like Microsoft Word and LibreOffice Writer,
Markdown authoring stores both content and markup together
in a human-readable tekst file.
::: {#fig-formality}
informal /---------formatted text----------\ formal
<------v-------------v-------------v-----------------------v---->
plain text informal markup formal markup binary format
(Markdown) (HTML, XML, etc.)
Markdown is informal, ASCII-based markup
[@Leonard2016, p. 4]
:::
HTML is itself a plaintext format,
but is less human-readable.
Similarly the format LaTeX is also plaintext,
but its markdown arguably distracts the reading process
[@Mailund2019chap2, p. 9].
Alternatives
Other human-readable document source formats exists.
TODO: briefly cover reStructuredText, Org-mode and AsciiDoc.
Integration
Markdown is in widespread use.
Major source forges use Markdown by default for README files
[@Github2025; @GitLab2025; @Codeberg2024].
Some major programming languages
natively support Markdown in embedded docstrings
in core tools
[@Microsoft2023; @Oracle2025; @RustTeam2024];
others offer optional support e.g. through plugins
[@Heesch2025; @Sphinx2025; @JSDoc2023].
Pandoc and Quarto
Pandoc is a document converter built around the markdown markup language,
able to parse from and serialise to many Markdown dialects
as well as equivalent subsets of other text markup languages
including HTML, LaTeX (and by extension PDF),
Office Open XML (as used by recent releases of Microsoft Word)
and OpenDocument (as used by OpenOffice and LibreOffice).
Pandoc is extensible,
supporting custom code loaded at runtime
either for custom parsing or serialising,
or for manipulating the intermediate internal content structure
called Abstract Syntax Tree (AST).
Pandoc supports redefining input and output formats
and manipulating the internal document structure
as part of the automated parts of the framework.
Pandoc is extendable.
Source and output format can be changed or completely redefined
and the internal document structure manipulated,
in the automated parts of the framework.
Collection of interrelated POSIX scripts and Pandoc extensions
for enabling semantic annotations in Markdown-based authoring workflows.
- filter extension to capture annotations
- identify semantic metadata in stylistic metadata part of Pandoc YAML header
- identify semantic metadata in content part of Pandoc document structure
- append semantic metadata to Pandoc YAML document header
- strip identified metadata from stylistic metadata and content
- output format extension to generate PDF
- read semantic metadata from Pandoc YAML document header
- structure semantic metadata as RDF triples
- append RDF triples serialized as part of XMP metadata in PDF
- output format extension to generate web page
- read semantic metadata from Pandoc YAML document header
- structure semantic metadata as RDF triples
- append RDF triples serialized as RDFa
Markdown provides intuitive and unobtrusive markup syntax
for structure like headers, emphasis, lists and hyperlinks.
Pandoc extends Markdown with syntax
for citation annotation
and an optional YAML metadata header.
Quarto extends Markdown further with syntax
for some styling and some convenience macros,
and applies templates for a uniform visual styling
across target document formats.
Interfaces
- Pandoc document object model (DOM)
- Resource Description Framework (RDF)
- Markdown
- CommonMark
