mkdocs-ini-includer 1.0.0

A MkDocs plugin to include INI file content in documentation

MkDocs INI Includer

This is a MkDocs plugin that allows a MkDocs site to include all or part of an INI file inside the docs at build time.

Why?

• Documenting the configuration system of an app without having to copy/paste config sections
• Showing the configuration for a specific feature

Features

• ✅ Include whole INI files
• ✅ Include specific sections (e.g., [section.name] and all sub-data)
• ✅ Preserve comments (useful docs for users)
• ✅ Support array keys like key1[] = abc, key1[] = def
• ✅ Simple embedding without complex parsing

Installation

pip install mkdocs-ini-includer

Configuration

Add the plugin to your mkdocs.yml:

plugins:
  - ini-includer:
      base_path: "path/to/your/ini/files"  # Optional: base path for INI files
      config_file: "app.ini"              # Optional: default INI file

Usage

Include Entire INI File

{% ini-include %}

Or specify a specific file:

{% ini-include file="config/app.ini" %}

Include Specific Section

{% ini-include section="database" %}

Examples

Given an INI file config/app.ini:

# Application configuration
[app]
name = MyApp
version = 1.0.0

# Database settings
[database]
host = localhost
port = 5432
# Connection pool settings
pool_size = 10

[database.ssl]
enabled = true
cert_path = /path/to/cert

Include entire file:

{% ini-include %}

Include only database section:

{% ini-include section="database" %}

This will include the [database] section and all its subsections like [database.ssl].

Notes

• File paths are relative to your docs_dir unless base_path is configured
• Comments and formatting are preserved
• Array keys (like key[]=value) are supported
• Error handling displays helpful messages in the generated docs