This script creates a mkdocs static site from a directory of documentation files.
The generated static site is used with MkDocs to build and serve the documentation.
It scans through all subdirectories of the given directory and searched for the documentation files (markdown), images and examples.
Then it creates new mkdocs project directory (if it is not already present) and copies all files to the relevant subdirectories into the docs directory of the mkdocs project.
./mkdocs
├── docs
│ ├── about.md
│ ├── index.md
│ ├── ipam/...
│ ├── vpc/...
│ └── ...
└── mkdocs.ymlThe script also generates a mkdocs.yml file based on the provided configuration settings and directory structure.
The script uses the title from the metadata of the documentation files to generate the navigation structure of the mkdocs site.
The metadata is stored in the YAML format in the beginning of the documentation file.
---
title: "Title of the documentation file"
---
# Title of the documentation file
Content...- Create Python virtual environment and activate it:
- Clone the script repository
3 Install the script using
pip:
pip install mkdocs-generate/.mkdocs-generate [--config CONFIG] [--print-config] [--backup] [--scan-dir SCAN_DIR] [--section-name SECTION_NAME] [--version]
--config CONFIG, -c CONFIG: Path to a YAML file with configuration settings. If not provided, default settings will be used.--print-config, -p: Print the default configuration settings.--backup, -b: Backup the existing docs directory if it exists. If not provided, the existing directory will be deleted and a new one will be created.--scan-dir SCAN_DIR, -s SCAN_DIR: Path to the directory to be scanned for documentation files. Default is the current directory.--section-name SECTION_NAME, -n SECTION_NAME: Name of the section under 'Content' in mkdocs.yml. Default is "Documentation".--version: Print the version of the script.
mkdocs-generate -c generate_config.yml -b -s ./tf-modules
0.1.4
This script is licensed under the MIT License. See the LICENSE file for more information.