The Gold Digger project uses mdBook as the foundation for its documentation system, integrating user guides, developer documentation, and API references into a unified site automatically built and deployed to GitHub Pages. The infrastructure emphasizes extensibility, automation, and strict markdown quality standards.

Documentation Infrastructure and Structure#

Documentation resides in the docs/ directory. The main configuration is in docs/book.toml, with markdown sources in docs/src/. The structure is defined in docs/src/SUMMARY.md and includes:

• User Guide: Installation (with platform-specific guides), quick start, configuration, output formats, and usage examples.
• Security: Database security, TLS/SSL configuration, migration guides, release verification, and best practices.
• Troubleshooting: Common issues, connection problems, integration testing, type safety, type errors, and performance.
• Developer Guide: Development setup, contributing, integration testing, TLS variants, architecture, API reference, release runbook, and related topics.
• API Reference: Rust API documentation generated by rustdoc and integrated into the site.

Example structure from SUMMARY.md:

# Summary

[Introduction](introduction.md)

# User Guide

- [Installation](installation/README.md)
  - [Windows](installation/windows.md)
  - [macOS](installation/macos.md)
  - [Linux](installation/linux.md)
- [Quick Start](usage/quick-start.md)
...
# Developer Guide

- [Development Setup](development/setup.md)
- [API Reference](development/api-reference.md)

See full structure.

mdBook Configuration, Preprocessors, and Plugins#

The documentation system leverages several mdBook preprocessors and plugins, configured in docs/book.toml:

• mdbook-admonish: Styled callouts for notes, warnings, and tips.
• mdbook-mermaid: Mermaid diagram rendering for architecture and flow diagrams.
• mdbook-linkcheck: Validates internal and external links during build.
• mdbook-toc: Generates a table of contents for long pages.
• mdbook-open-on-gh: Adds "Edit this page on GitHub" links.
• mdbook-tabs: Enables tabbed content for platform-specific or alternative instructions.
• mdbook-i18n-helpers: Provides infrastructure for future internationalization.

Example plugin configuration:

[preprocessor.admonish]
command = "mdbook-admonish"

[preprocessor.mermaid]
command = "mdbook-mermaid"

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

[preprocessor.linkcheck]
command = "mdbook-linkcheck"

[preprocessor.open-on-gh]
command = "mdbook-open-on-gh"

[preprocessor.tabs]
command = "mdbook-tabs"

[preprocessor.i18n-helpers]
command = "mdbook-i18n-helpers"

Reference.

The HTML output uses the "navy" theme, includes custom CSS and JavaScript, and provides direct edit links to GitHub.

Automated Build and Deployment Workflow#

Documentation is built and deployed automatically via a GitHub Actions workflow (.github/workflows/docs.yml). The workflow triggers on pushes and pull requests to the main branch and on manual dispatch. The workflow uses pinned commit SHAs for GitHub Actions to improve security and reliability. The build process includes:

1. Checkout code and set up the Rust toolchain.
2. Install mdBook and all required plugins.
3. Build the mdBook site with mdbook build in the docs directory.
4. Build Rust API documentation with cargo doc --no-deps --document-private-items and copy the output to docs/book/api.
5. Upload the generated site as an artifact and deploy it to GitHub Pages if on the main branch.

Deployment diagram:

Workflow details.

Markdown Linting and Formatting Rules#

Markdown quality is enforced using both markdownlint-cli2 and mdformat:

• markdownlint-cli2 (.markdownlint-cli2.jsonc): Enforces heading increments, consistent unordered list style, 2-space indentation, 100-character line length (except in code blocks/tables), 80-character heading line length, and specific rules for thematic breaks, fenced code, and code span style. It allows only sibling duplicate headings, disables some rules, and ignores certain files and directories.
• mdformat (.mdformat.toml): Formats markdown with a 100-character wrap, LF line endings, and enables extensions for GitHub Flavored Markdown, tables, admonitions, and more. It preserves mdBook-specific syntax such as includes, admonitions, and mermaid diagrams.

Example .mdformat.toml:

wrap = 100
end_of_line = "lf"
extensions = [
    "gfm",
    "frontmatter",
    "footnote",
    "simple_breaks",
    "tables",
    "gfm_alerts",
    "toc",
    "wikilink",
]

See markdownlint config and mdformat config.

Local Build and Validation Workflow for Contributors#

Contributors can build, serve, and validate documentation locally using the just command recipes and pre-commit hooks:

• just docs-install: Installs mdBook and all required plugins.
• just docs-build: Builds both the mdBook site and the Rust API docs, integrating them into a single output.
• just docs-serve: Serves the documentation locally with live reload at http://localhost:3000.
• just docs-clean: Removes generated documentation artifacts.
• just docs-check: Runs mdBook build and checks markdown formatting with mdformat.

Pre-commit hooks are configured to run documentation link checks and markdown formatting validation automatically before commits. To set up pre-commit hooks:

pip install pre-commit
pre-commit install
# Optionally, validate all files:
pre-commit run --all-files

Contributor workflow details.

This setup ensures that all documentation changes are validated for structure, formatting, and link integrity before merging or deployment.