Documentation

MD-Models can export your data models to documentation formats, making it easy to generate comprehensive, interactive documentation for your data structures.

MkDocs

The MkDocs exporter generates Markdown documentation files formatted for use with MkDocs, a static site generator for project documentation. This exporter creates human-readable documentation that includes:

• Visual graph representation of your data model structure
• Detailed type definitions with all attributes and their properties
• Enumeration documentation with value mappings
• Cross-references between related types
• Ontology and prefix information

Usage

To generate MkDocs documentation from your MD-Models file:

md-models convert -i <model> -t mk-docs

For example:

md-models convert -i model.md -t mk-docs -o documentation.md

Generated Output

The MkDocs exporter generates a comprehensive documentation page that includes:

Visual Graph

An interactive Mermaid flowchart that visualizes:

• All object types and enumerations in your model
• Relationships between types (when one type references another)
• Clickable links to navigate to each type’s documentation section

The graph is displayed in a collapsible quote block using MkDocs’ ??? quote syntax.

Ontologies Section

If your model includes ontology prefixes, they are listed with links to their namespace URIs. This helps users understand the semantic context of your data model.

Types Section

Each object in your model is documented with:

• Type name: The name of the object type
• Description: The docstring from your model
• Attributes: A detailed list of all attributes including:
  • Attribute name (marked with * if required)
  • Data type(s) with automatic linking to referenced types
  • Array notation (list[Type]) for multiple values
  • Attribute description/docstring
  • Default values (if specified)
  • Additional options (e.g., primary key, unique constraints)

Types are automatically cross-referenced - when an attribute references another type in your model, it becomes a clickable link to that type’s section.

Enumerations Section

All enumerations are documented in table format showing:

• Enumeration name and description
• A table mapping each enum alias to its corresponding value

Integration with MkDocs

The generated Markdown file can be directly included in your MkDocs site. To use it:

1. Add the generated file to your docs/ directory
2. Include it in your mkdocs.yml navigation:

nav:
  - Home: index.md
  - API Reference: documentation.md

1. The documentation will automatically render with:
   • Syntax highlighting for code blocks
   • Interactive Mermaid diagrams (requires mkdocs-mermaid2-plugin)
   • Cross-referenced links between types
   • Responsive tables for enumerations

Configuration Options

The MkDocs exporter supports a nav configuration option. When set, the generated documentation will include navigation elements. Without it, the navigation is hidden by default, making it suitable for embedding in existing MkDocs sites.

Documentation Format Comparison