Advanced Quarto for Documentation

Gregory M. Kapfhammer

September 29, 2025

Document engineering

  • What is document engineering?
    • Creating documents using code
    • Manipulating and analyzing text data
    • Building documentation systems
    • “Prosegrammers” combine prose and programming
  • Why is it important?
    • Documentation quality affects software success
      • Poor docs cause user confusion
      • Clear docs increase adoption
      • Automated docs reduce maintenance cost

Extended features of Markdown and Quarto

  • Links and images
  • Code blocks and inline code
  • Executable code blocks with Quarto
  • Live output from code execution
  • Tables for structured data
  • Blockquotes for emphasis

Links can connect your content

Source Code for creating links

**External Link:**
Visit [GitHub](https://github.com) for version control.

**Internal Link:**
See the [syllabus](../../syllabus/index.qmd) for details.

**Reference Link:**
Check out [Python documentation][python-docs].

[python-docs]: https://docs.python.org/3/

Rendered Output:

External Link: Visit GitHub for version control.

Internal Link:
See the syllabus for details.

Images offer visual enhancement

Source Code example for images

**Basic Image:**
![Prosegrammers Logo](../../images/Prosegrammers-Logo.svg)

Prosegrammers Logo

Code blocks show technical content

Source Code for inline and fenced code block

**Inline Code:**
Use the `print()` function in Python.

**Fenced Code Block:**
```python
def greet_prosegrammer(name: str) -> str:
    """Greet a document engineer professionally."""
    return f"Hello, {name}! Ready to engineer some documents?"

print(greet_prosegrammer("Alice"))
```
  • Inline code blocks highlight technical terms
  • Fenced code blocks preserve formatting
  • Supported languages include Python, R, Julia, … and more!

Tables help to present structured data

Source Code for table in Markdown

| Tool | Purpose | Prosegrammer Use |
|------|---------|------------------|
| Git | Version control | Track document changes |
| Python | Programming | Automate documentation |
| Quarto | Publishing | Create professional docs |
| Markdown | Markup | Write readable content |
  • Tables are useful for structured data
  • Use pipes | and dashes - to create tables
  • Organize the data in rows and columns
  • Define a header row to label the columns
  • Table rendering is customizable with CSS

Tables show structured data

Tool Purpose Prosegrammer Use
Git Version control Track document changes
Python Programming Automate documentation
Quarto Publishing Create professional docs
Markdown Markup Write readable content
  • Tables organize structured data in our documentation
  • This table summarizes key tools for prosegrammers
  • Can you inspect the source code to see how it was styled?

Blockquotes emphasize key ideas

Source code for creating a blockquote

> Document engineering is the art of creating clear, 
> maintainable, and professional documentation that 
> serves both human readers and automated systems.
>
> — A thoughtful prosegrammer

Rendered Output:

Document engineering is the art of creating clear, maintainable, and professional documentation that serves both human readers and automated systems.

— A thoughtful prosegrammer

Mathematical Expressions

Source code for mathematical expressions

**Inline Math:**
The complexity is $O(n^2)$ for this algorithm.

**Display Math:**
$$
\text{Document Quality} = \frac{\text{Clarity} \times \text{Accuracy}}{\text{Complexity}}
$$

Rendered Output:

Inline Math: The complexity is \(O(n^2)\) for this algorithm.

Display Math with a silly equation: \[ \text{Document Quality} = \frac{\text{Clarity} \times \text{Accuracy}}{\text{Complexity}} \]

Quarto offers ways to enhanced markdown

  • Executable code blocks with live output
  • Cross-references for figures and tables
  • Citations and bibliography management
  • Multiple output formats from single source

Quarto makes Markdown a powerful publishing platform!

Executable Python Code

Running live code makes documentation interactive and testable! Code block format details? Try out pyodide!

Quick reminders for prosegrammers!

  • Document engineering means blending code and prose to build resources for both humans and machines
  • Quarto and Markdown empower you to easily create documents that are clear, interactive, and professional
  • Prosegrammers use these tools to automate, analyze, and publish documentation that stands out