Skip to content

📖 User Manual

This manual provides instructions for configuring and building documentation with the MkDocs-Kit toolchain.

⚙️ Configuration (mkdocs.yml)

To unlock all features of MkDocs-Kit, register the custom Diagrams plugin and configure the output options in your mkdocs.yml:

site_name: Project Documentation
use_directory_urls: false  # REQUIRED: Ensures links point to index.html instead of directories

plugins:
  - search
  - mkdocs_kit.plugin: {}

[!IMPORTANT] Setting use_directory_urls: false is critical. It ensures that local HTML previews (using file:// scheme) resolve navigation paths successfully without requiring an active web server.

🛠️ Command Line Interface

MkDocs-Kit exposes a CLI through mkdocs_kit.cli. The basic commands are:

Build Documentation

Generates static HTML files (inside site/), a single unified PDF manual (documentation.pdf), and UNIX man pages (inside site/man/):

python3 -m mkdocs_kit.cli build

Serve Site

Starts a local development server with live-reloading:

python3 -m mkdocs_kit.cli serve

Clean Build Output

Removes generated directories and files:

python3 -m mkdocs_kit.cli clean

🖨️ PDF Generation (WeasyPrint)

MkDocs-Kit compiles all pages defined in the nav section of mkdocs.yml into a single, high-fidelity PDF manual using WeasyPrint.

Scaling & Page-Fit Rules

By default, the PDF stylesheet enforces the following constraints: * Aspect Ratio Preservation: Diagrams and SVGs scale proportionally without distortion. * Page Bounds Fitting: Large SVG diagrams are capped at a maximum height of 22cm to ensure they fit cleanly inside the A4 printable area.

/* Inside pdf.py custom print stylesheet */
.diagram-plantuml svg, .diagram-wireviz svg, .diagram-rackdiag svg {
    max-width: 100% !important;
    max-height: 22cm !important;
    width: auto !important;
    height: auto !important;
    object-fit: contain !important;
}

🐧 UNIX Man Page Generation

To generate UNIX Man pages, MkDocs-Kit scans the documentation structure for markdown files that contain a specific metadata block (frontmatter) at the very top.

Frontmatter Structure

Add the following YAML block at the beginning of your markdown page:

---
man: true
man_section: 1
man_name: my-utility
man_description: Executes custom configuration sweeps.
---

Build Result

When you run the build command, MkDocs-Kit compiles these marked pages and writes them to the site/man/ output folder (e.g. site/man/man1/my-utility.1).

📊 CSV File Inclusion, Interactive Sorting & Filtering

MkDocs-Kit supports embedding inline or external CSV files in Markdown using ```csv blocks.

<div class="diagram-error" style="color: #ff3333; border: 1px solid #ff3333; padding: 10px; margin: 10px 0; background-color: #ffe6e6; border-radius: 4px; font-family: monospace;"><strong>Error rendering csv:</strong><pre style="margin: 5px 0 0 0; white-space: pre-wrap;">CSV file not found: data/employees.csv (resolved: /home/runner/work/mkdocs-kit/mkdocs-kit/doc/docs/data/employees.csv)</pre></div>
  • HTML Features: Interactive column header click-to-sort, instant multi-column search, and paginated navigation.
  • PDF Features: Build-time dynamic filtering and column sorting, rendered into multi-page tables with repeating headers (thead { display: table-header-group; }).

📈 Plotly & D3.js Integration

Plotly Charts (plotly)

<div class="mkdocs-kit-plotly-wrapper" id="plotly-chart-936233">
<div class="mkdocs-kit-plotly-container" style="width: 100%; min-height: 350px;"><svg xmlns="http://www.w3.org/2000/svg" width="600" height="350" viewBox="0 0 600 350" style="background-color: #ffffff; font-family: system-ui, sans-serif;"><text x="300.0" y="30" text-anchor="middle" font-size="16" font-weight="bold" fill="#333333">Quarterly Revenue</text><line x1="60" y1="50" x2="60" y2="300" stroke="#ccc" stroke-width="1"/><line x1="60" y1="300" x2="570" y2="300" stroke="#ccc" stroke-width="1"/><line x1="60" y1="300.0" x2="570" y2="300.0" stroke="#f0f0f0" stroke-width="1"/><text x="52" y="304.0" text-anchor="end" font-size="10" fill="#666">0.0</text><line x1="60" y1="237.5" x2="570" y2="237.5" stroke="#f0f0f0" stroke-width="1"/><text x="52" y="241.5" text-anchor="end" font-size="10" fill="#666">77.5</text><line x1="60" y1="175.0" x2="570" y2="175.0" stroke="#f0f0f0" stroke-width="1"/><text x="52" y="179.0" text-anchor="end" font-size="10" fill="#666">155.0</text><line x1="60" y1="112.5" x2="570" y2="112.5" stroke="#f0f0f0" stroke-width="1"/><text x="52" y="116.5" text-anchor="end" font-size="10" fill="#666">232.5</text><line x1="60" y1="50.0" x2="570" y2="50.0" stroke="#f0f0f0" stroke-width="1"/><text x="52" y="54.0" text-anchor="end" font-size="10" fill="#666">310.0</text><text x="123.75" y="318" text-anchor="middle" font-size="11" fill="#555">Q1</text><rect x="85.5" y="203.22580645161293" width="76.5" height="96.77419354838709" fill="#3498db" rx="2"/><text x="251.25" y="318" text-anchor="middle" font-size="11" fill="#555">Q2</text><rect x="213.0" y="106.45161290322582" width="76.5" height="193.54838709677418" fill="#3498db" rx="2"/><text x="378.75" y="318" text-anchor="middle" font-size="11" fill="#555">Q3</text><rect x="340.5" y="154.83870967741933" width="76.5" height="145.16129032258067" fill="#3498db" rx="2"/><text x="506.25" y="318" text-anchor="middle" font-size="11" fill="#555">Q4</text><rect x="468.0" y="50.0" width="76.5" height="250.0" fill="#3498db" rx="2"/></svg></div>
<script>
(function() {
const container = document.getElementById("plotly-chart-936233").querySelector(".mkdocs-kit-plotly-container");
const config = {"data": [{"x": ["Q1", "Q2", "Q3", "Q4"], "y": [120, 240, 180, 310], "type": "bar", "marker": {"color": "#3498db"}}], "layout": {"title": "Quarterly Revenue"}};
if (typeof Plotly !== "undefined") {
container.innerHTML = "";
Plotly.newPlot(container, config.data || [], config.layout || {}, {responsive: true});
} else {
if (!window.plotlyScriptLoading) {
window.plotlyScriptLoading = true;
const script = document.createElement("script");
script.src = "https://cdn.plot.ly/plotly-2.27.0.min.js";
script.onload = function() {
document.querySelectorAll(".mkdocs-kit-plotly-wrapper").forEach(w => {
const c = w.querySelector(".mkdocs-kit-plotly-container");
const cfg = w.dataset.config ? JSON.parse(w.dataset.config) : null;
if (c && cfg) { c.innerHTML = ""; Plotly.newPlot(c, cfg.data || [], cfg.layout || {}, {responsive: true}); }
});
};
document.head.appendChild(script);
}
document.getElementById("plotly-chart-936233").dataset.config = JSON.stringify(config);
}
})();
</script>
</div>

D3.js Diagrams (d3)

<div class="mkdocs-kit-d3-wrapper" id="d3-chart-617553">
<div class="mkdocs-kit-d3-container" style="width: 100%; min-height: 350px;"><svg xmlns="http://www.w3.org/2000/svg" width="600" height="350" viewBox="0 0 600 350" style="background-color: #ffffff; font-family: system-ui, sans-serif;"><text x="300.0" y="30" text-anchor="middle" font-size="16" font-weight="bold" fill="#333333">Performance Metrics</text><line x1="60" y1="50" x2="60" y2="300" stroke="#ccc" stroke-width="1"/><line x1="60" y1="300" x2="570" y2="300" stroke="#ccc" stroke-width="1"/><text x="187.5" y="318" text-anchor="middle" font-size="11" fill="#555">Alpha</text><rect x="111.0" y="162.80487804878047" width="153.0" height="137.19512195121953" fill="#9b59b6" rx="3"/><text x="187.5" y="156.80487804878047" text-anchor="middle" font-size="10" font-weight="bold" fill="#333">45</text><text x="442.5" y="318" text-anchor="middle" font-size="11" fill="#555">Beta</text><rect x="366.0" y="50.0" width="153.0" height="250.0" fill="#9b59b6" rx="3"/><text x="442.5" y="44.0" text-anchor="middle" font-size="10" font-weight="bold" fill="#333">82</text></svg></div>
<script>
(function() {
const container = document.getElementById("d3-chart-617553").querySelector(".mkdocs-kit-d3-container");
const spec = {"type": "bar", "data": [{"label": "Alpha", "value": 45}, {"label": "Beta", "value": 82}], "options": {"title": "Performance Metrics"}};
if (typeof d3 !== "undefined") {
// Interactivity hook
} else if (!window.d3ScriptLoading) {
window.d3ScriptLoading = true;
const script = document.createElement("script");
script.src = "https://cdn.jsdelivr.net/npm/d3@7";
document.head.appendChild(script);
}
})();
</script>
</div>
  • HTML: Interactive Plotly and D3.js chart components.
  • PDF: Pre-rendered static vector SVGs compiled into WeasyPrint PDFs.

📦 Automated Distribution Build Scripts

MkDocs-Kit includes deterministic, multi-distribution build scripts located in scripts/:

# Auto-detect local OS distribution and run full build & test sequence:
./scripts/build-all.sh

# Run explicit distribution build script:
./scripts/build-debian.sh -o ./output   # Builds Debian/Ubuntu .deb package
./scripts/build-fedora.sh -o ./output   # Builds Fedora/RHEL .rpm package
./scripts/build-arch.sh -o ./output     # Builds Arch Linux .pkg.tar.zst package