Mickaël CANOUIL Template

Complete Guide

Mickaël CANOUIL, Ph.D. ORCID
pro@mickael.canouil.dev

Independent Contractor

Jane Doe ORCID

Example University

Thursday, the 29th of January, 2026

Introduction

This document showcases all features of the Mickaël CANOUIL template for Quarto. It covers HTML, Typst (PDF), and Reveal.js (presentations) formats. It serves as both an educational resource and a quick reference guide.

Navigate using the table of contents to find specific features. Each section includes working examples you can copy and adapt for your own documents.

Document Organisation

This demonstration is organised into five main sections:

  1. Template-Specific Components (Section 2): Value boxes, panels, badges, dividers, progress bars, card grids, executive summaries, grid background, mermaid diagrams, and code annotations.
  2. Quarto Features (Section 3): Figures, tables, mathematics, callouts, tabsets, and code blocks.
  3. Typography and Layout (Section 4): Headings, lists, quotations, asides, and layout features.
  4. Advanced Features (Section 5): Footnotes, citations, custom cross-references, document types, Reveal.js options, and special sections.
  5. Conclusion (Section 6): Summary of all features covered.

Cross-references work throughout this document. For example, see Section 2 for template components or Figure 1 for a figure example.

Template-Specific Components

The template provides nine specialised components for professional document creation. These components are unique to this Typst template and enhance visual communication.

Value Boxes

Value boxes display metrics, KPIs, and statistics in a visually appealing format. They are ideal for dashboards, reports, and presentations.

Basic Value Boxes

42%
Growth Rate
1.2M€
Total Revenue
98%
Customer Satisfaction
24
Active Projects

Value Box Icons

Value boxes support icons to indicate trends or status:

18%
Quarterly Growth
5%
Operating Costs
42%
Market Share

Value Box Grid Layout

Arrange multiple value boxes using Quarto’s layout-ncol feature:

42%
Metric A
87%
Metric B
15%
Metric C

Value Box Parameters:

  • value: The numeric value to display (required).
  • unit: Unit symbol (%, €, $, etc).
  • label: Description text (required).
  • icon: Icon shortcuts (up ↑, down ↓, stable —) or any UTF-8 character.
  • colour: Colour types (success, warning, danger, info, neutral) or hex colours (#ff0000).
  • background: Optional background colour override.
  • show-border: Display border around the box (default: true).
  • alignment: Content alignment (center, left, right; default: center).
  • alt: Optional alt text for accessibility when using grid layouts (wraps grid in figure with alt text).

Info Panels

Info panels highlight content with eight distinct styles. They provide more flexibility than callouts and support rich content.

Panel Style Variants

Subtle panels provide minimal emphasis for background information or supplementary notes. Use when you want gentle visual separation without strong emphasis.

Emphasis panels offer moderate highlighting for important information that deserves attention. They create visual hierarchy without being overwhelming.

Accent panels create strong visual impact for key insights or critical information. Use sparingly for maximum effect.

Outline panels provide clean borders without background fill. They maintain clarity whilst keeping the design minimal and unobtrusive.

Status-Based Panels

Information Panel

Info panels use note callout colours for explanatory content. Panel titles can be set via the title attribute or as the first heading inside the panel.

Success Panel

Success panels highlight positive outcomes, achievements, or completed tasks. They use green tones to convey accomplishment and success.

Warning Panel

Warning panels alert readers to important caveats, limitations, or potential issues. Use them to draw attention to matters that require careful consideration.

Critical Panel

Danger panels emphasise critical information, errors, or severe warnings. They demand immediate attention through bold red styling.

Panels with Rich Content

Rich Content Example

Panels support any content type:

  • Unordered and ordered lists.
  • Code blocks and inline code like function().
  • Mathematical notation: \(E = mc^2\).
  • Bold text, italic text, and bold italic text.

This versatility makes panels ideal for technical documentation and reports.

Panel Parameters:

  • style: Style variant (subtle, emphasis, accent, outline, info, success, warning, danger).
  • title: Optional title text (or use first heading inside panel).
  • icon: Optional icon (any UTF-8 character or emoji).
  • border-width: Border thickness (default: 1pt).
  • radius: Corner radius (default: 8pt).
  • inset: Internal padding (default: 1.2em).
  • breakable: Allow page breaks inside panel (default: false).

Status Badges

Status badges provide compact inline indicators for status, categories, tags, and labels. They appear inline with text and use colour-coded styling.

Badge Colour Types

Project Status: Approved

Draft This section is under review.

Critical Requires immediate attention.

New Feature Recently added capability.

Internal For internal use only.

Badges with Icons

Badges support optional icons using any UTF-8 character or emoji:

Completed Pending Error

Beta Documentation

Multiple Badges

Combine multiple badges to provide comprehensive status information:

Document Status: Active High Priority Review Required

Badge Syntax:

  • Span syntax (all formats): [Text]{.badge colour="success" icon="✓"}.
  • Shortcode (HTML and Reveal.js only): {{< badge text="Text" colour="success" icon="✓" >}}.

Badge Parameters:

  • colour: Badge colour type (success, warning, danger, info, neutral).
  • icon: Optional icon (any UTF-8 character or emoji).
  • inline: Display inline or as block (default: true).

Dividers

Decorative dividers provide visual separation between sections without using headings.

Basic Divider

Divider with Label

Divider Style Variants

Divider Parameters:

  • style: Divider style (solid, dashed, dotted, ornamental, gradient).
  • label: Optional centred label text.
  • thickness: Line thickness (default: 1pt).
  • width: Line width as percentage (default: 50%).

Progress Bars

Progress bars visualise completion, distribution, or proportions.

Project Completion
75%
Budget Utilisation
45%
Server Capacity
90%
Storage Used
50%
Baseline Progress
25%

Progress Bar with Custom Colours

Custom Colour Progress
65%

Progress Bar Parameters:

  • value: Progress percentage (0-100, required).
  • label: Description text (required).
  • colour: Colour type (success, warning, danger, info, neutral) or hex colour.
  • height: Bar height (default: 1.5em).
  • show-percentage: Display percentage label (default: true).

Card Grids

Card grids provide flexible layouts for displaying content in card format.

Basic Card Grid

Performance

Optimised for speed with minimal overhead and efficient rendering across all platforms.

99.9% uptime guarantee

Security

Enterprise-grade security with end-to-end encryption, compliance, and regular audits.

SOC 2 Type II certified

Scalability

Scales effortlessly from small teams to global enterprises with millions of users.

10M+ active users

Card Style Variants

Cards support three distinct styles:

Subtle Style

Light background with subtle border. This is the default card style.

Outlined Style

Clear border with transparent background. Clean and minimal appearance.

Filled Style

Bold filled background with contrasting text. Maximum visual impact.

Card Grid Parameters:

  • columns: Number of columns (1-4).
  • alt: Optional alt text for accessibility (wraps grid in figure with alt text).
  • Card style: subtle, outlined, or filled.
  • Card colour: Custom accent colour (for filled style).
  • Cards support title (## Heading), content, and footer (after —).

Standalone Cards

Individual cards can be used outside of card grids for single-item emphasis:

Standalone Card Example

This card is used independently, not within a card-grid. It provides the same styling options as cards within grids.

Filled Standalone Card

Filled cards with custom colours work perfectly as standalone components. Ideal for call-to-action blocks or featured content.

Executive Summary

Executive summary blocks provide prominent, professional summary sections for reports.

Executive Summary

This quarter exceeded all strategic targets across revenue, customer satisfaction, and project delivery.

Key Achievements:

  • Revenue grew 18% year-over-year, surpassing projected targets.
  • Customer satisfaction score reached 94%, a new company record.
  • All major projects delivered on time and within budget.
  • Team productivity improved 22% through process optimisation.

Strategic Priorities for Next Quarter:

  1. Scale platform infrastructure to support 50,000 concurrent users.
  2. Expand into three new European markets (Germany, France, Spain).
  3. Enhance security framework with SOC 2 Type II certification.
  4. Launch mobile application for iOS and Android platforms.

Overall Project Status: On Track High Confidence

Executive Summary Parameters:

  • title: Custom title (default: “Executive Summary”).
  • show-corner-brackets: Include decorative corner brackets (default: true).

Quarto Features

The template supports all standard Quarto features with enhanced styling.

Figures

Simple Figure

Figure 1: An example figure demonstrating basic figure capabilities with caption and cross-referencing.

Reference the figure using Figure 1 in your text.

Figure with Custom Width

Figure 2: A wider figure spanning more of the page width to demonstrate flexible sizing.

See Figure 2 for the wider figure example.

Subfigures

(a) First subfigure showing left panel.

(b) Second subfigure showing right panel.
Figure 3: Two subfigures arranged side by side demonstrating multi-panel layouts.

Reference the complete figure as Figure 3, or individual subfigures as Figure 3 (a) and Figure 3 (b).

Tables

Simple Table

Table 1: A simple table demonstrating basic table capabilities.
Column A Column B Column C
Value 1 Value 2 Value 3
Value 4 Value 5 Value 6
Value 7 Value 8 Value 9

Reference tables using Table 1 in your text.

Tables with Subtables

Table 2: Two subtables arranged side by side demonstrating multi-table layouts.
(a) First subtable.
Alpha Beta
A1 B1
(b) Second subtable.
Gamma Delta
G1 D1

Table with Column Alignment

Table 3: Column alignment demonstration (left, centre, right).
Left Aligned Centre Aligned Right Aligned
Text Text Text
123 456 789
Alpha Beta Gamma

See Table 3 for alignment examples.

Complex Data Table

Table 4: Template colour scheme comparison between light and dark modes.
Feature Light Mode Dark Mode Notes
Background #fafafa #333333 Page background colour
Foreground #333333 #fafafa Primary text colour
Muted #666666 #999999 Secondary text colour
Accent #e67e22 #e67e22 Brand accent colour
Link #0066cc #66aaff Hyperlink colour
Corner Brackets Enabled Enabled Signature branding element

Detailed colour information is available in Table 4.

Mathematics

Inline Mathematics

Inline mathematical expressions like \(\alpha + \beta = \gamma\), \(\int_0^1 f(x) \, dx\), and \(\sum_{i=1}^{n} i = \frac{n(n+1)}{2}\) integrate seamlessly with text.

The quadratic formula \(x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\) and Euler’s identity \(e^{i\pi} + 1 = 0\) demonstrate mathematical typesetting quality.

Display Mathematics

Einstein’s famous mass-energy equivalence relation:

\[ E = mc^2 \tag{1}\]

The quadratic formula for solving \(ax^2 + bx + c = 0\):

\[ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \tag{2}\]

Maxwell’s equations governing electromagnetic fields:

\[ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\epsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \epsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} \tag{3}\]

Matrix equation demonstrating linear algebra:

\[ \begin{bmatrix} a_{11} & a_{12} & a_{13} \\ a_{21} & a_{22} & a_{23} \\ a_{31} & a_{32} & a_{33} \end{bmatrix} \begin{bmatrix} x_1 \\ x_2 \\ x_3 \end{bmatrix} = \begin{bmatrix} b_1 \\ b_2 \\ b_3 \end{bmatrix} \tag{4}\]

Cross-reference equations using Equation 1, Equation 2, Equation 3, or Equation 4.

Callouts

Quarto’s standard callout blocks provide contextual information.

Note

Note callouts provide additional information or context without interrupting the main narrative flow. They are ideal for supplementary details that enhance understanding.

Pro Tip

Tip callouts offer helpful suggestions, best practices, or recommendations. Use them to share expertise and guide readers towards optimal approaches.

Important Information

Important callouts highlight essential details that readers must not miss. They emphasise critical information that affects understanding or outcomes.

Warning

Warning callouts alert readers to caveats, limitations, or potential issues. They help readers avoid common pitfalls or misunderstandings.

Caution

Caution callouts warn about significant risks, dangers, or problematic scenarios. They demand attention to prevent errors or adverse consequences.

Panel Tabsets

Panel tabsets organise content into tabs in HTML-based formats. In Typst (PDF), tabs are converted to a hierarchical heading structure since Typst does not support tabs.

This tab contains introductory content. In Typst, this becomes a subsection under “Overview” as a heading.

This tab provides more detailed information.

  • First detail item.
  • Second detail item.
  • Third detail item.
python
# Example code in a tab
def greet(name: str) -> str:
    return f"Hello, {name}!"

Tabset Behaviour:

  • HTML/Reveal.js: Renders as interactive tabs.
  • Typst: Tab titles become headings; content headings are nested appropriately.

Code Blocks

Inline Code

Variable names like my_variable, function calls like calculate_mean(), and commands like quarto render appear inline with special formatting.

Code Windows

When extensions.mcanouil.code-window.enabled: true is set (the default), code blocks with a filename attribute display a macOS-style window header. With extensions.mcanouil.code-window.auto-filename: true (the default), code blocks without explicit filenames automatically show the language name in small-caps styling.

fibonacci.py
def fibonacci(n: int) -> int:
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)
analysis.R
# Load data and create summary
data <- read.csv("data.csv")
summary(data)

With auto-filename: true, code blocks without explicit filenames show the language name:

Python Code Block

python
def fibonacci(n: int) -> int:
    """Calculate the nth Fibonacci number using recursion."""
    if n <= 1:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

def fibonacci_iterative(n: int) -> int:
    """Calculate the nth Fibonacci number iteratively."""
    if n <= 1:
        return n
    a, b = 0, 1
    for _ in range(2, n + 1):
        a, b = b, a + b
    return b

# Example usage
result = fibonacci_iterative(10)
print(f"F(10) = {result}")

R Code Block

r
# Load required libraries
library(ggplot2)
library(dplyr)

# Create sample data
data <- data.frame(
  x = 1:10,
  y = c(2, 4, 6, 8, 10, 12, 14, 16, 18, 20)
)

# Create visualisation
ggplot(data, aes(x = x, y = y)) +
  geom_point(size = 3, colour = "steelblue") +
  geom_line(colour = "steelblue") +
  labs(
    title = "Linear Relationship",
    x = "X Variable",
    y = "Y Variable"
  ) +
  theme_minimal()

Bash Script

bash
#!/bin/bash
# Automated backup script

SOURCE="/home/user/documents"
BACKUP="/backup/documents"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Create backup directory if it doesn't exist
mkdir -p "${BACKUP}"

# Compress and archive
tar -czf "${BACKUP}/backup_${TIMESTAMP}.tar.gz" "${SOURCE}"

# Verify backup
if [ $? -eq 0 ]; then
    echo "Backup completed successfully: backup_${TIMESTAMP}.tar.gz"
else
    echo "Backup failed" >&2
    exit 1
fi

Grid Background

The template supports a subtle grid background overlay for HTML and Reveal.js formats. This is controlled via the extensions.mcanouil.grid-background option.

YAML Configuration:

yaml
extensions:
  mcanouil:
    grid-background: true  # Enable grid background (default: false)

When enabled, a faint grid pattern appears behind all content. The grid uses a 50px spacing with a colour derived from the foreground and background colours.

Format Availability:

  • HTML: Applied to the page body.
  • Reveal.js: Applied to slide backgrounds via a pseudo-element overlay.
  • Typst: Not available (PDF format).

Mermaid Diagrams

The template supports Mermaid diagrams with automatic dark theme styling.

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[End]
    D --> E
Figure 4: A simple flowchart demonstrating Mermaid diagram support.

See Figure 4 for the rendered diagram.

Code Annotations

Code annotations allow readers to explore code explanations interactively. In Reveal.js, the code-annotation-fragments plugin enables fragment-based navigation through annotations.

python
def calculate_area(radius: float) -> float:
    """Calculate the area of a circle."""
    import math
    return math.pi * radius ** 2
1
Function signature with type hints for input and output.
2
Docstring describing the function purpose.
3
Import the math module for access to pi.
4
Apply the area formula: A = pi * r^2.

Configuration:

yaml
# Enable code annotations (set in YAML front matter)
code-annotations: select  # Options: select, hover, none

# Reveal.js fragment navigation for annotations
extensions:
  mcanouil:
    code-annotation-fragments: true

Typography and Layout

Heading Levels

This section demonstrates all six heading levels with their respective styling.

Level 3 Heading

Content under level 3 heading demonstrating hierarchy and spacing.

Level 4 Heading

Content under level 4 heading with appropriate font sizing.

Level 5 Heading

Content under level 5 heading maintaining visual consistency.

Level 6 Heading

Content under level 6 heading (the deepest available level).

Lists

Unordered Lists

  • First item demonstrating unordered list styling.
  • Second item with nested elements:
    • Nested item 2.1 showing second-level indentation.
    • Nested item 2.2 with consistent formatting.
      • Deeply nested item 2.2.1 demonstrating third-level nesting.
      • Deeply nested item 2.2.2 with proper alignment.
  • Third item returning to top level.

Ordered Lists

  1. First numbered item establishing sequence.
  2. Second numbered item with sub-steps:
    1. Sub-step 2.1 using alphabetic numbering.
    2. Sub-step 2.2 maintaining hierarchy.
    3. Sub-step 2.3 showing consistent styling.
  3. Third numbered item completing the sequence.

Definition Lists

Term One
Definition of term one providing clear explanation and context.
Term Two
Definition of term two with more detailed information. Definitions can span multiple lines whilst maintaining proper formatting and indentation.
Complex Term
A more complex definition that includes bold text, italic text, and inline code to demonstrate rich formatting within definition lists.

Quotations and Asides

Block Quotes

“The best way to predict the future is to invent it.”

— Alan Kay

Longer block quotes demonstrate styling across multiple lines and paragraphs. They maintain consistent formatting, proper indentation, and visual hierarchy.

Multi-paragraph quotes preserve spacing and readability whilst clearly distinguishing quoted content from the main narrative.

Asides

Caution

.aside and .column-margin are not implemented in Typst yet.

This is regular paragraph text in the main column.

More regular text continues in the main column after the aside.

Margin notes offer another way to include supplementary content. They appear in the page margin and support rich formatting.

Layout Features

Multi-Column Layout

Column 1: Content in the first column demonstrating side-by-side layout capabilities. This column contains the first half of the content with proper formatting and spacing.

Column 2: Content in the second column showing parallel information. This column contains the second half, creating a balanced two-column presentation.

Three-Column Layout

First: Brief content in column one.

Second: Brief content in column two.

Third: Brief content in column three.

Highlighted Text Blocks

This block uses highlighted styling for emphasis and visual impact. Use highlighted blocks for key takeaways, important statements, or critical information that deserves special attention. They create visual hierarchy whilst maintaining readability.

Section Pages

When section-page: true is enabled, level-1 headings are rendered on dedicated section pages with special styling:

  • Banner: A coloured banner at 20% from the top of the page, spanning 75% of the page width from the left edge.
  • Inverted colours: The banner uses the foreground colour as background, with the section title in the background colour.
  • Heading underline: The banner includes the signature gradient underline with inverted colours.
  • Subsection outline: Below the banner, an outline of subsections within that section is displayed (respecting toc-depth).
  • Symmetric margins: Section pages use symmetric margins, similar to the title page.
  • Single-column: Section pages are always single-column, regardless of the document’s column setting.
  • No margin section: The professional style margin section is suppressed on section pages.

Section pages apply to all level-1 headings except those with outlined: false (such as TOC and list-of sections).

YAML Configuration:

yaml
format:
  mcanouil-typst:
    section-page: true    # Enable section pages
    toc-depth: 3          # Controls outline depth on section pages

Cross-References

This document includes comprehensive cross-references throughout:

Sections:

Figures:

Tables:

Equations:

Advanced Features

Footnotes

This sentence includes a footnote.1 Another sentence demonstrates multiple footnotes working together.2

Extended discussion with several footnotes creates a rich layer of supplementary information.3

Citations and Bibliography

Citations integrate seamlessly with the bibliography system. See Example and Author (2024) for a comprehensive example of citation formatting.

Multiple citations can be grouped together (Example and Author 2024, 2024), and citations work with inline text as well. According to Example and Author (2024), proper citation practices enhance academic rigour.

The bibliography appears automatically at the end of the document.

Custom Cross-References

The template supports custom cross-reference types beyond the standard sections, figures, tables, and equations.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis sagittis posuere ligula sit amet lacinia. Duis dignissim pellentesque magna, rhoncus congue sapien finibus mollis. Ut eu sem laoreet, vehicula ipsum in, convallis erat. Vestibulum magna sem, blandit pulvinar augue sit amet, auctor malesuada sapien. Nullam faucibus leo eget eros hendrerit, non laoreet ipsum lacinia. Curabitur cursus diam elit, non tempus ante volutpat a. Quisque hendrerit blandit purus non fringilla. Integer sit amet elit viverra ante dapibus semper. Vestibulum viverra rutrum enim, at luctus enim posuere eu. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

Text 1: Example text demonstrating custom cross-reference types.

Reference custom floats using Text 1 in your text.

Document Types (Typst)

The Typst format supports multiple document types via the document-type parameter. Each type provides a distinct layout and structure suited to its purpose.

Available Document Types:

  • report (default): Standard report layout with title page, table of contents, and section pages.
  • invoice: Invoice layout for billing documents.
  • letter: Formal letter layout.
  • cv: Curriculum vitae layout.

YAML Configuration:

yaml
format:
  mcanouil-typst:
    document-type: report  # Options: report, invoice, letter, cv

Reveal.js Closing Slide

The Reveal.js format supports a custom closing slide with a photo and social links.

YAML Configuration:

yaml
format:
  mcanouil-revealjs:
    closing-slide:
      photo: "https://github.com/mcanouil.png"
      social:
        website: https://mickael.canouil.fr
        github: mcanouil
        linkedin: MickaelCanouil
        bluesky: mickael.canouil.fr
        mastodon: https://fosstodon.org/%40MickaelCanouil

The closing slide displays the author photo alongside social media links, providing a professional end to presentations.

Reveal.js Extension Options

The Reveal.js format supports several extension-specific options under the extensions.mcanouil namespace:

yaml
extensions:
  mcanouil:
    section-outline: true           # Show subsection outline on section slides.
    date-superscript: true          # Format ordinal dates (1st, 2nd, 3rd).
    hide-title-slide-chrome: true   # Hide menu/logo/footer on title slide.
    favicon-from-logo: true         # Generate favicon from slide logo.
    code-annotation-fragments: true # Enable annotation fragment navigation.
    debug-borders: false            # Show debug borders on slides.

Special Sections

Special sections (appendix and supplementary) automatically relocate to the document end with customised numbering.

Conclusion

This demonstration showcases the complete feature set of the Mickaël CANOUIL template across HTML, Typst (PDF), and Reveal.js (presentations) formats.

Template-Specific Components

The template provides specialised components:

  1. Value Boxes (Section 2.1): Display metrics, KPIs, and statistics with icons and colours.
  2. Info Panels (Section 2.2): Highlight content with eight style variants (subtle, emphasis, accent, outline, info, success, warning, danger).
  3. Status Badges (Section 2.3): Provide compact inline status indicators with five colour types.
  4. Dividers (Section 2.4): Create visual separation with multiple style options (solid, dashed, dotted, gradient, ornamental).
  5. Progress Bars (Section 2.5): Visualise completion and proportions with customisable colours.
  6. Cards (Section 2.6): Individual card components for featured content with three style variants.
  7. Card Grids (Section 2.6): Present multiple cards in flexible grid layouts.
  8. Executive Summaries (Section 2.7): Create prominent summary blocks for professional reports.
  9. Highlighted Blocks (Section 4.5): Draw attention to key information with subtle background emphasis.
  10. Grid Background (Section 3.7): Subtle grid overlay for HTML and Reveal.js formats.
  11. Code Annotations (Section 3.9): Interactive code explanations with fragment navigation.
  12. Mermaid Diagrams (Section 3.8): Flowcharts and diagrams with automatic dark theme styling.

Quarto Features

Standard Quarto features work seamlessly with enhanced styling:

  • Figures (Section 3.1): Simple figures, custom widths, subfigures, and featured image styling.
  • Tables (Section 3.2): Simple tables, column alignment, and complex data tables.
  • Mathematics (Section 3.3): Inline expressions and display equations with cross-references.
  • Callouts (Section 3.4): Five callout types (note, tip, important, warning, caution).
  • Tabsets (Section 3.5): Panel tabsets with automatic Typst conversion to headings.
  • Code Blocks (Section 3.6): Syntax highlighting for Python, R, Bash, inline code, and macOS-style code windows.

Typography and Layout

Comprehensive typography and layout features:

  • Headings (Section 4.1): Six heading levels with gradient underlines.
  • Lists (Section 4.3): Unordered, ordered, and definition lists with nesting.
  • Quotations (Section 4.4): Block quotes and asides with proper styling.
  • Layout Features (Section 4.5): Multi-column layouts and highlighted blocks.
  • Cross-References (Section 4.7): Seamless referencing throughout the document.

Advanced Features

  • Document Types (Section 5.4): Report, invoice, letter, and CV layouts for Typst.
  • Closing Slide (Section 5.5): Custom closing slide with photo and social links for Reveal.js.
  • Reveal.js Options (Section 5.6): Section outlines, date formatting, and more.
  • Special Sections (Section 5.7): Auto-relocating appendix and supplementary sections.

Customisation Options

The template supports extensive customisation through YAML parameters:

  • Colour Modes: Light and dark modes with optional colour overrides.
  • Decorative Elements: Corner brackets, margin decoration, title page backgrounds, and heading underlines.
  • Typography: Custom fonts, sizes, weights, and line heights.
  • Page Layout: Flexible paper sizes, margins, and column configurations.
  • Watermarks: Text or image watermarks with customisable opacity, angle, and colour.
  • Logo: Flexible logo positioning and sizing with alternative text.
  • Special Sections: Configurable appendix and supplementary sections with custom numbering.

Accessibility

The template is designed with PDF accessibility (PDF/UA-1) compliance in mind:

  • PDF/UA-1 Standard: Enabled by default via pdf-standard: ua-1 (requires Typst >= 0.14).
  • Semantic Structure: Proper heading hierarchy, tables with headers, and semantic elements.
  • Decorative Elements as Artifacts: Corner brackets, margin decorations, watermarks, and other decorative elements are marked as PDF artifacts so screen readers skip them.
  • Alt Text Support: Grid-based components (card grids, value box grids) support an optional alt parameter for accessibility descriptions.
  • Non-Colour Differentiation: Callouts include default titles (Note, Tip, Warning, etc.) to ensure information is not conveyed by colour alone.
  • WCAG AA Contrast: Colours are validated to meet WCAG AA contrast requirements.

Getting Started

To use these features in your own documents:

  1. Install the template extension: quarto add mcanouil/quarto-mcanouil@0.9.0.
  2. Set the format in YAML front matter: format: mcanouil-html, format: mcanouil-typst, or format: mcanouil-revealjs.
  3. Customise template parameters as demonstrated in this document’s YAML.
  4. Copy and adapt examples from each section as needed.

References

Example, Jane, and John Author. 2024. ‘An Example Article for Demonstrating Citations’. Journal of Examples, ahead of print. https://doi.org/10.1234/example.2024.

Additional Configuration

This appendix section demonstrates the special sections feature. Content marked with the .appendix class automatically relocates to the document end with special numbering (A.1, A.2, etc).

Configuration Examples

Additional YAML configuration examples for advanced customisation:

yaml
format:
  mcanouil-typst:
    # Advanced Typography
    heading-colour: "#e67e22"          # Custom heading colour

    # Advanced Table Styling
    table-stroke: 1pt                 # Custom border thickness
    table-inset: 8pt                  # Custom cell padding
    table-fill: alternating           # Striped table rows

    # Advanced Quote Styling
    quote-width: 85%                  # Custom blockquote width
    quote-align: left                 # Custom blockquote alignment

    # Advanced Link Styling
    link-underline: false             # Disable link underlines
    link-colour: "#3498db"            # Custom link colour

Complete YAML Options Reference

This section documents all available YAML front matter options for customising the template.

Style Options

yaml
# Document style
style: "professional"  # "academic" or "professional"

# Colour mode
brand-mode: "light"  # "light" or "dark"

# Document type (Typst only)
document-type: "report"  # "report", "invoice", "letter", or "cv"

# Override default colours (optional)
colour-background: "#FFFFFF"  # Hex colour code
colour-foreground: "#333333"  # Hex colour code
colour-muted: "#999999"       # Hex colour code

Decorative Elements

yaml
# Control decorative features
show-corner-brackets: true          # Corner brackets around content blocks
show-margin-decoration: true        # Decorative elements in margins
show-title-page-background: true    # Geometric background on title page
show-heading-underlines: true       # Underlines beneath headings

Logo Configuration

yaml
show-logo: true          # Display logo in header
logo-width: 40pt         # Logo width (omit to use height only)
logo-inset: 4pt          # Padding around logo
logo-alt: "Logo text"    # Alternative text for accessibility

Watermark Options

yaml
watermark-text: "DRAFT"         # Text watermark
watermark-image: "path/to/img"  # Image watermark path
watermark-opacity: 10%          # Transparency (0-100%)
watermark-angle: "-45deg"       # Rotation angle
watermark-size: 4em             # Text size for text watermarks
watermark-colour: "gray"        # Colour for text watermarks

Typography

yaml
# Fonts
font-body: "Alegreya Sans"      # Body text font
font-headings: "Alegreya Sans"  # Heading font
font-size: 11pt                 # Base font size

# Heading styling
heading-weight: "bold"          # Font weight
heading-style: "normal"         # Font style (normal/italic)
heading-colour: null            # Override colour (null uses foreground)
heading-line-height: 0.65em     # Line height for headings
title-size: 24pt                # Title font size
subtitle-size: 14pt             # Subtitle font size

Page Layout

yaml
papersize: "a4"       # Paper size (a4, letter, a5, etc.)
columns: 1            # Number of columns (1 or 2)

# Custom margins (optional)
margin:
  top: 2.5cm
  bottom: 2.5cm
  left: 2.5cm
  right: 2.5cm

Document Structure

yaml
toc: true                     # Include table of contents
list-of: true                 # Include list of figures/tables
number-sections: true         # Number section headings
section-numbering: "1.1.1."   # Numbering pattern
section-pagebreak: true       # Page break before level 1 headings
section-page: true            # Dedicated section pages for level-1 headings

Accessibility

yaml
# PDF/UA-1 accessibility standard (requires Typst >= 0.14)
pdf-standard: ua-1            # Produces accessible tagged PDFs

Special Sections

yaml
special-sections:
  references:
    name: "References"        # Section name
    numbering: "none"         # Numbering pattern ("none" for unnumbered)
    prefix: false             # Show section name prefix
  appendix:
    name: "Appendix"
    numbering: "A.a."         # Appendix numbering (A.1, A.2, etc.)
    prefix: true              # Show "Appendix" prefix
  supplementary:
    name: "Supplementary"
    numbering: "I.i."         # Roman numerals (I.1, I.2, etc.)
    prefix: true

Table Styling

yaml
table-stroke: "0.5pt"        # Border thickness
table-inset: 5pt             # Cell padding
table-fill: null             # Header background colour (null for foreground)
yaml
quote-width: 75%             # Blockquote width
quote-align: "center"        # Blockquote alignment
link-underline: true         # Underline hyperlinks
link-underline-opacity: 60%  # Link underline transparency
link-colour: null            # Override link colour (null uses foreground)

Professional Style Options

Additional options available when style: "professional":

yaml
institute: "Company Name"    # Footer left content (defaults to first author affiliation)
copyright: "© 2026 Company"  # Footer right content
license: "MIT License"       # Licence info (combined with copyright if both present)
title-page: true             # Dedicated title page mode

Extensions Configuration

yaml
extensions:
  mcanouil:
    # Grid background (HTML and Reveal.js)
    grid-background: false           # Subtle grid overlay (default: false)
    # Code window styling (all formats)
    code-window:
      enabled: true                  # macOS-style code windows (default: true)
      auto-filename: true            # Auto-show language name (default: true)
    # HTML only
    hide-navbar-title: true          # Hide title from navbar (default: true)
    # Reveal.js only
    section-outline: true            # Subsection outline on section slides
    date-superscript: true           # Ordinal date formatting (1st, 2nd)
    hide-title-slide-chrome: true    # Hide chrome on title slide
    favicon-from-logo: true          # Generate favicon from logo
    code-annotation-fragments: true  # Fragment navigation for annotations
    debug-borders: false             # Debug borders on slides

Closing Slide (Reveal.js)

yaml
closing-slide:
  photo: "https://example.com/photo.png"
  social:
    website: https://example.com
    github: username
    linkedin: username
    bluesky: handle.bsky.social
    mastodon: https://instance/@user

Margin Section Configuration

Note: Margin sections are only displayed in professional style. Currently, margin section styling is controlled by internal constants in margin-section.typ:

  • MARGIN-SECTION-REFERENCE-SIZE: Reference font size for measuring text widths (default: 12pt).
  • MARGIN-SECTION-FILL-RATIO: Target fill ratio for vertical constraint; the longest heading occupies at most this percentage of available height (default: 90%).
  • MARGIN-SECTION-MAX-MARGIN-RATIO: Maximum font size as percentage of left margin width after rotation (default: 50%).
  • MARGIN-SECTION-POSITION-HORIZONTAL: Horizontal position percentage within margin (default: 85%).
  • MARGIN-SECTION-OPACITY: Text opacity level (default: 70%).
  • MARGIN-SECTION-WEIGHT: Font weight (default: “bold”).
  • MARGIN-SECTION-ROTATION: Rotation angle (default: -90deg for vertical text).
  • MARGIN-SECTION-MIN-SIZE: Minimum text size for accessibility (default: 9pt).
  • MARGIN-SECTION-HEADING-LEVEL: Heading level to display (default: 1 for top-level sections).

Behaviour:

  • The margin section shows the most recent heading of the configured level.
  • Section titles persist across pages until a new heading of that level appears.
  • Supports special section numbering for appendices, supplementary materials, and references.
  • Automatic font size calculation: Queries all headings in the document, measures their text width, and calculates the optimal font size subject to two constraints: (1) the longest heading fills at most 90% of available height, and (2) font size does not exceed 50% of the left margin width.
  • Consistent sizing across all pages without text wrapping.
  • Gracefully fails (returns none) if required parameters are missing.

Configuration options may be added in future versions for user customisation via YAML.

Default Values

If an option is not specified, the following defaults apply:

Option Default Description
style "academic" Academic style with simple header/footer
document-type "report" Document layout type (Typst only)
brand-mode "light" Light colour scheme
show-corner-brackets true Decorative brackets enabled
show-logo true Logo displayed when provided
font-size 11pt Standard readable size
columns 1 Single-column layout
section-pagebreak true Level 1 headings start new page
section-page false Dedicated section pages disabled
toc false Table of contents not generated
list-of true List of figures/tables generated
number-sections true Section headings numbered
pdf-standard ua-1 PDF/UA-1 accessibility standard

Validation

The template validates options and provides helpful error messages:

  • Colour values must be valid hex codes or colour names.
  • Size values must include units (pt, em, cm, etc.).
  • Boolean values must be true or false.
  • Special section numbering must be valid Typst numbering patterns.

Feature Reference Table

Table 5: Complete feature reference with syntax and parameters.
Component Shortcode/Class Key Parameters
Value Box value, unit, label, icon, colour, alt
Panel .panel style, title, icon
Badge .badge colour, icon
Divider style, label, width, thickness
Progress Bar value, label, colour
Card .card style, colour
Card Grid .card-grid columns, alt
Executive Summary .executive-summary title
Highlight .highlight (none)

Colour Schemes

This supplementary section demonstrates additional special section functionality. Content marked with .supplementary appears after appendices with Roman numeral numbering (I.1, I.2, etc).

Light Mode Colours

Table 6: Light mode colour scheme.
Element Hex Code RGB Usage
Background #fafafa rgb(250,250,250) Page background
Foreground #333333 rgb(51,51,51) Primary text
Muted #666666 rgb(102,102,102) Secondary text
Accent #e67e22 rgb(230,126,34) Brand colour

Dark Mode Colours

Table 7: Dark mode colour scheme.
Element Hex Code RGB Usage
Background #333333 rgb(51,51,51) Page background
Foreground #fafafa rgb(250,250,250) Primary text
Muted #999999 rgb(153,153,153) Secondary text
Accent #e67e22 rgb(230,126,34) Brand colour

Callout Colours (WCAG AA Compliant)

Table 8: Callout colour accessibility compliance.
Callout Type Hex Code Contrast Ratio Accessibility
Note #0066cc 7.5:1 AA Large Text, AAA Normal
Tip #009955 6.8:1 AA Large Text, AAA Normal
Warning #cc6600 5.2:1 AA Large Text
Important #cc0000 5.9:1 AA Large Text
Caution #b38f00 6.1:1 AA Large Text, AAA Normal
Speaker photo

Mickaël CANOUIL, Ph.D. ORCID

Independent Contractor

pro@mickael.canouil.dev