Using with MdBook

MdBook is a popular tool for creating documentation from Markdown files. Requiem integrates seamlessly with MdBook, allowing requirements to live alongside documentation.

Overview

Requiem requirements are Markdown files, making them naturally compatible with MdBook. You can:

Include requirements in your MdBook table of contents
Embed requirements in documentation chapters
Mix requirements with narrative documentation
Generate complete documentation sites with embedded requirements

Basic Setup

Project Structure

my-book/
├── book.toml          ← MdBook configuration
└── src/
    ├── SUMMARY.md     ← Table of contents
    ├── config.toml    ← Requiem configuration
    ├── chapter1.md    ← Documentation
    ├── USR-001.md     ← Requirement
    └── USR-002.md     ← Requirement

Requiem Configuration

Since the src/ directory contains both requirements and documentation, configure Requiem to allow non-requirement files:

src/config.toml:

_version = "1"
allow_unrecognised = true  # Important: allows chapter1.md, SUMMARY.md, etc.

MdBook Configuration

book.toml:

[book]
title = "My Project Documentation"
authors = ["Your Name"]
language = "en"
src = "src"

[build]
build-dir = "book"

No special MdBook configuration needed for Requiem requirements!

Including Requirements in Table of Contents

Requirements can be listed in SUMMARY.md like any other chapter:

src/SUMMARY.md:

# Summary

[Introduction](./introduction.md)

# Requirements

- [User Requirements](./user-requirements.md)
  - [USR-001: User Authentication](./USR-001.md)
  - [USR-002: Data Export](./USR-002.md)
  - [USR-003: Email Validation](./USR-003.md)

- [System Requirements](./system-requirements.md)
  - [SYS-001: Authentication Service](./SYS-001.md)
  - [SYS-002: Export API](./SYS-002.md)

# User Guide

- [Getting Started](./getting-started.md)
- [Features](./features.md)

Requirements appear as chapters in the generated book. The HRID in the first heading (e.g., # USR-001 User Authentication) becomes the page title automatically.

Embedding Requirements

Use MdBook's include feature to embed requirements in documentation chapters:

src/user-guide.md:

# User Guide

## Authentication

Our authentication system satisfies the following requirement:

{{#include USR-001.md}}

To log in, navigate to...

When MdBook builds, USR-001.md content is embedded directly.

Selective Inclusion

Include only the requirement body (skip frontmatter but keep the heading):

{{#include USR-001.md:6:}}

This skips the YAML frontmatter and includes the heading and body.

Line counting:

---                    ← Line 1
_version: '1'
uuid: ...
created: ...
---                    ← Line 5
# USR-001 Title        ← Line 6 (keep this!)

Requirement text...    ← Line 7 onwards

Adjust the line number based on your frontmatter length. The heading with the HRID should typically be kept as it provides context.

Formatting Requirements

Display Frontmatter

To show frontmatter in documentation:

src/requirements-format.md:

# Requirement Format

Requirements include metadata in YAML frontmatter:

{{#include USR-001.md}}

MdBook renders the entire file, including frontmatter as a code block.

Hide Frontmatter

To show only the requirement text:

Option 1: Use line ranges

{{#include USR-001.md:7:}}

Option 2: Create requirement summary files

src/usr-001-summary.md:

<!-- Manually maintained summary without frontmatter -->
The system shall validate user email addresses according to RFC 5322.

Then include the summary file in documentation.

Custom Formatting with Preprocessors

For advanced formatting (e.g., extracting specific fields), use MdBook preprocessors:

mdbook-linkcheck - Validate links
mdbook-toc - Generate table of contents
Custom preprocessor - Extract HRID, UUID, parent links from frontmatter

Working Example

See the complete example in the Requiem repository:

git clone https://github.com/danieleades/requirements-manager
cd requirements-manager/examples/mdbook

Example Structure

examples/mdbook/
├── book.toml
├── src/
│   ├── SUMMARY.md
│   ├── chapter_1.md
│   ├── USR-001.md
│   └── USR-002.md
└── README.md

Build the Example

Install MdBook:

cargo install mdbook

Build the book:

mdbook build

View output:

mdbook serve --open

Your browser opens showing the documentation with requirements included.

Best Practices

1. Organize by Type

Group requirements in SUMMARY.md:

# Summary

# User Requirements
- [USR-001](./USR-001.md)
- [USR-002](./USR-002.md)

# System Requirements
- [SYS-001](./SYS-001.md)
- [SYS-002](./SYS-002.md)

2. Use Subdirectories

For large projects, organize requirements in subdirectories:

src/
├── SUMMARY.md
├── requirements/
│   ├── user/
│   │   ├── USR-001.md
│   │   └── USR-002.md
│   └── system/
│       ├── SYS-001.md
│       └── SYS-002.md
└── guides/
    └── user-guide.md

SUMMARY.md:

# Summary

# Requirements
- [User Requirements](./requirements/user/USR-001.md)
- [System Requirements](./requirements/system/SYS-001.md)

3. Link Requirements

Link between requirements using standard Markdown links:

USR-001.md:

This requirement is implemented by [SYS-001](./SYS-001.md).

MdBook generates clickable links in the output.

4. Embed in Context

Embed requirements in relevant documentation sections:

user-guide.md:

# User Guide

## Email Validation

{{#include requirements/USR-003.md:7:}}

To validate emails, the system checks...

Keeps requirements and documentation synchronized.

5. Separate Config

Use separate config.toml for Requiem:

src/
├── config.toml      ← Requiem config (allow_unrecognised = true)
├── book.toml        ← Don't confuse with MdBook config
└── ...

Note: MdBook's config is book.toml in the root, not in src/.

Limitations

Frontmatter Rendering

MdBook doesn't parse YAML frontmatter specially. It renders as:

---
_version: '1'
uuid: 4bfeb7d5-...
created: 2025-07-22T12:19:56.950194157Z
---

Requirement text...

The frontmatter appears as a code block (triple-dash markers).

Workaround: Use line ranges to skip frontmatter (see Formatting Requirements).

No Dynamic Traceability

MdBook doesn't generate traceability matrices or parent-child diagrams automatically.

Workaround: Generate diagrams with external tools and include as images:

# Traceability

![Requirement Hierarchy](./diagrams/traceability.svg)

No HRID Validation

MdBook doesn't validate requirement references.

Workaround: Use CI to validate:

# .github/workflows/docs.yml
- name: Validate requirements
  run: req clean
  working-directory: ./src

- name: Build documentation
  run: mdbook build

Advanced Techniques

Generating Traceability Pages

Use scripts to generate traceability documentation:

generate-traceability.sh:

#!/bin/bash
# Generate a markdown page showing parent-child relationships

echo "# Requirement Traceability" > traceability.md
echo "" >> traceability.md

for req in USR-*.md; do
    hrid=$(basename "$req" .md)
    echo "## $hrid" >> traceability.md
    # Extract and format parent links
    # ...
done

Run before MdBook build:

./generate-traceability.sh
mdbook build

Custom MdBook Preprocessor

Create a preprocessor to enhance requirement rendering:

Rust preprocessor example:

#![allow(unused)]
fn main() {
// Extract HRID and UUID from frontmatter
// Add custom formatting
// Generate cross-reference links
}

See MdBook documentation for details.

GitHub Pages Deployment

Host your requirements documentation:

# .github/workflows/deploy.yml
name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install MdBook
        run: cargo install mdbook
      - name: Build book
        run: mdbook build
        working-directory: ./docs
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/book

Example Documentation Structure

Comprehensive documentation with requirements:

docs/
├── book.toml
└── src/
    ├── SUMMARY.md
    ├── config.toml             ← Requiem config
    │
    ├── introduction.md          ← Narrative docs
    ├── architecture.md
    ├── getting-started.md
    │
    ├── requirements/            ← Requirements
    │   ├── user/
    │   │   ├── USR-001.md
    │   │   └── USR-002.md
    │   ├── system/
    │   │   ├── SYS-001.md
    │   │   └── SYS-002.md
    │   └── traceability.md      ← Generated
    │
    └── user-guide/              ← User guides
        ├── authentication.md    ← Embeds USR-001, SYS-001
        └── export.md            ← Embeds USR-002, SYS-002

Troubleshooting

Requirements Not Appearing in Book

Problem: Requirements listed in SUMMARY.md don't appear.

Diagnosis:

Check file paths in SUMMARY.md are correct
Ensure files exist at specified paths
Run mdbook build -v for verbose output

Solution: Verify paths match file structure exactly.

Frontmatter Renders as Code Block

Problem: YAML frontmatter shows as markdown code block.

Explanation: Expected behavior. MdBook doesn't parse YAML frontmatter.

Solution: Use line ranges to skip frontmatter (see Selective Inclusion).

Requiem Validation Fails

Problem: req clean reports errors about non-requirement files.

Solution: Set allow_unrecognised = true in config.toml:

_version = "1"
allow_unrecognised = true

Includes Don't Work

Problem: {{#include USR-001.md}} doesn't embed content.

Diagnosis:

Check file path is correct relative to including file
Check MdBook version (includes supported in 0.3.0+)

Solution: Use correct relative paths:

{{#include ./USR-001.md}}  # If in same directory
{{#include ../requirements/USR-001.md}}  # If in subdirectory

Summary

Key Points:

Requiem requirements are compatible with MdBook out of the box
Set allow_unrecognised = true in Requiem config when mixing with docs
Include requirements in SUMMARY.md or embed with {{#include}}
Use line ranges to skip frontmatter if desired
Combine requirements with narrative documentation for comprehensive docs

Benefits:

Single source of truth
Requirements stay synchronized with docs
Easy navigation and search
Professional-looking documentation

Limitations:

Frontmatter renders as code block
No automatic traceability diagrams
No HRID validation (use external tools)

Next Steps

See Using with Sphinx for Python documentation
Review Version Control Best Practices for managing requirements in Git

Keyboard shortcuts

Requiem User Guide