Accessible markdown-based workflows

Published on: 03/10/2023 · Last updated on: 17/07/2026

What are markdown-based publishing tools?

Markdown-based publishing tools allow you to write content in a simple, plain-text format that can be converted into a range of outputs such as web pages, PDFs, Word documents, and presentations slides.

These tools extend basic Markdown by allowing you to combine:

  • Text and headings
  • Code (e.g. R, Python)
  • Figures, tables and equations
  • Outputs generated directly from code

Common tools include:

  • Quarto (recommended for new projects)
  • R Markdown
  • bookdown
  • ClavertonDown (for authors needing specific control over Theorem, Proof, Lemma environments)

Why use markdown-based tools instead of LaTeX?

Markdown-based tools offer a more accessible and flexible alternative to LaTeX:

  • Better accessibility support and flexible outputs. A single source document can be exported to HTML, PDF, Word, or slides. See common barriers to digital access in STEM content
  • Simple to learn and use. Markdown syntax is simple and readable, requiring far less technical setup than LaTeX and there are many templates to get going.
  • Some similarities to LaTeX. Markdown equation syntax is the same as LaTeX, and referencing of figures/equations and citations (via bibtex).
  • Multimedia support. It is straightforward to include images, video, audio, and interactive content, which is more difficult in LaTeX.
  • Integrated code and simulations. Tools like Quarto and R Markdown allow you to embed code that generates figures, tables, and simulations automatically.
  • Customisable. The package ecosystem for markdown-based tools is less mature than LaTeX, but it’s also possible to create custom packages, behaviour and appearances too.

Switching from LaTeX to markdown-based tools

If you are used to writing in LaTeX, moving to markdown-based tools such as Quarto or R Markdown is usually straightforward—particularly when creating new content.

For most users:

  • Maths syntax is the same. You can continue to write equations using standard LaTeX notation (e.g. \( ... \) or $ ... $), which will render correctly in outputs.
  • Less setup is required. You can focus more on content and less on formatting or document configuration.

Converting existing LaTeX documents

Migrating existing LaTeX materials can be more challenging.

Automated tools

Conversion tools (e.g. Pandoc) can help convert .tex files into Markdown formats, but:

  • Not all LaTeX commands are supported
  • Custom macros and packages may not translate cleanly
  • Complex layouts may be lost or simplified

Manual editing is usually required

You may need to:

  • Rewrite figures, tables, or cross-references
  • Replace unsupported LaTeX features
  • Simplify document structure
  • Some features (e.g. specialised packages or formatting tricks) may not have direct equivalents outside LaTeX.

Which tool should I use?

Quarto

Who is this for?

  • Staff developing new teaching materials
  • Users working with R, Python, or data-driven content
  • Anyone needing flexible outputs (HTML, PDF, Word)
  • Mature slide presentation support

Advantages

  • Modern, actively developed tool
  • Simple, consistent syntax
  • Strong support for multiple output formats
  • Integrates well with VS Code and RStudio

Disadvantages

  • Advanced features require familiarity with YAML and configuration

Quarto Examples

Getting started with Quarto

  1. View the Get started to download Quarto CLI tool
  2. Set it up with your editor of choice (e.g. VSCode, RStudio, Jupyter, etc)
  3. Create a new document or start a new project for a populated example
  4. Read the Quarto guide to find out more.

Using Quarto to Produce and Design Accessible HTML Course Materials for Mathematics

ClavertonDown

Who is this for?

ClavertonDown is for authors needing specific control over Theorem, Proof, Lemma environments. The ClavertonDown project was developed in MASH to allows mathematics lecturers access to mathematics environments (numbering and referencing of Theorem, Proof, Lemma environments) that were not natively supported in other markdown-based tools.

Advantages

  • Builds on established markdown
  • Provides support for equation environments used in pure Mathematics.
  • Supports a dedicated clear print PDF format, which is the most often requested by disabled students in the Maths department

Disadvantages

  • Less flexible than standalone tools
  • Requires following a defined workflow
  • Can be harder to adopt for small or individual projects

Getting started with ClavertonDown

See the supporting ClavertonDown example book which demonstrates the functionality, documents usage and install instructions.

R Markdown or bookdown

Who is this for?

  • Existing R and Rstudio users
  • Teaching contexts with established R workflows

Advantages

  • Widely used and well-supported
  • Straightforward integration with R
  • Large ecosystem of tutorials and examples

Disadvantages

  • Knowledge of R is not essential, but is limiting for authors unfamiliar with R (consider using Quarto)
  • Many features now replicated (and improved) in Quarto

Getting started with bookdown

bookdown examples

Jupyter Notebooks

Who is this for?

  • Python-based teaching and data science

Advantages

  • Interactive and widely used
  • Good for demonstrations and exploratory work

Disadvantages

  • Harder to produce polished, longer structured documents – consider using Quarto instead.
  • More limited output flexibility (HTML, PDF only)

Sharing outputs with students

The workflows outlined above will create HTML pages (and optionally PDF, docx and epub outputs) that can be packaged as a standalone mini website. Please follow the guidance for publishing an HTML mini-site to Moodle – Learning and Teaching Hub

Where can I find more support?

Join the bookdown usergroup on Microsoft Teams for community support in all markdown-based authoring tools.

Was this article helpful?

Related Articles