Index.md Configuration
The IndexConfigFile manages the docs/index.md file, which serves as the
homepage for your MkDocs documentation site.
Overview
Creates a documentation index file that:
- Uses the project name with "Documentation" suffix as the header
- Includes all standard badges (tooling, code quality, package info, CI/CD, documentation)
- Displays the project description from
pyproject.toml - Provides a professional starting point for documentation
- Allows users to add custom content below the header
Inheritance
Inherits from: BadgesMarkdownConfigFile
What this means:
- Markdown file format (
.mdextension) - Automatically generates badges from project metadata
- Includes project name and description
- Validation checks for required elements (badges, description, project name)
- Users can add content after the generated header
- File is considered correct if it contains all required elements
File Location
Path: docs/index.md (docs directory)
Extension: .md - Standard Markdown extension.
Filename: index - The homepage for MkDocs documentation sites.
How It Works
Automatic Generation
When initialized via uv run pyrig mkroot, the docs/index.md file is created
with:
- Project name header: Uses project name from
pyproject.tomlwith " Documentation" suffix - Badge sections: Five categories of badges (tooling, code quality, package info, CI/CD, documentation)
- Project description: Quoted description from
pyproject.toml - Horizontal rules: Visual separators for clean layout
Generated Content
For a project named "myapp" with description "A sample application":
# myapp Documentation
<!-- tooling -->
[](https://github.com/Winipedia/pyrig)
[](https://github.com/astral-sh/uv)
[](https://podman.io/)
[](https://pre-commit.com/)
[](https://www.mkdocs.org/)
<!-- code-quality -->
[](https://github.com/astral-sh/ruff)
[](https://github.com/astral-sh/ty)
[](https://github.com/PyCQA/bandit)
[](https://pytest.org/)
[](https://codecov.io/gh/owner/myapp)
[](https://github.com/rvben/rumdl)
<!-- package-info -->
[](https://pypi.org/project/myapp/)
[](https://www.python.org/)
[](https://github.com/owner/myapp/blob/main/LICENSE)
<!-- ci/cd -->
[](https://github.com/owner/myapp/actions/workflows/health_check.yml)
[](https://github.com/owner/myapp/actions/workflows/release.yml)
<!-- documentation -->
[](https://owner.github.io/myapp)
---
> A sample application
---
Content Generation Logic
The content generation inherits from BadgesMarkdownConfigFile and adds "
Documentation" suffix to the project name.
Key behavior:
- Calls parent class to generate base content with badges
- Replaces first occurrence of project name with "{project_name} Documentation"
- This transforms "# myapp" into "# myapp Documentation"
Dynamic Configuration
The index file adapts to your project automatically:
Project Name
Automatically uses your project name from pyproject.toml [project] name
field with " Documentation" suffix.
Project Description
Displays the project description from pyproject.toml [project] description
field as a blockquote below the badges.
Repository Information
Extracts repository owner and name from Git remote URL for badge links.
Python Versions
Shows supported Python versions from pyproject.toml requires-python field in
the Python badge (e.g., 3.10|3.11|3.12).
Badge Categories
1. Tooling Badges
- pyrig: Built with pyrig
- uv: Package manager
- Container: Podman containerization
- pre-commit: Pre-commit hooks enabled
- MkDocs: Documentation generator
2. Code Quality Badges
- ruff: Linting and formatting
- ty: Strict type checking
- bandit: Security scanning
- pytest: Testing framework
- codecov: Code coverage
- rumdl: Markdown linting
3. Package Info Badges
- PyPI: Package version and link
- Python: Supported Python versions
- License: Project license
4. CI/CD Badges
- CI: Health check workflow status
- CD: Release workflow status
5. Documentation Badge
- Documentation: Link to GitHub Pages docs
Usage
Automatic Creation
The file is automatically created when you run:
uv run pyrig mkroot
Adding Custom Content
Simply add your content after the generated header:
# myapp Documentation
<!-- badges here -->
---
> A sample application
---
## Welcome
This is the documentation for myapp.
## Features
- Feature 1
- Feature 2
## Getting Started
...
The validation only checks that required elements exist, so you can add as much content as you want.
Validation Logic
The validation checks that the index file contains all required elements
(inherited from BadgesMarkdownConfigFile):
Required elements:
- All badges from all categories
- Project description
- Project name
Flexible structure: As long as these elements exist somewhere in the file, it's considered valid. You can add custom content anywhere.
Best Practices
- Keep the header: Don't remove the generated badges and description
- Add content below: Append your documentation after the horizontal rules
- Organize with sections: Use
##headers for main sections - Link to other pages: Reference other documentation pages
- Update description: Keep
pyproject.tomldescription current
Integration with MkDocs
The docs/index.md file is referenced in mkdocs.yml:
site_name: myapp
nav:
- Home: index.md
This makes it the homepage of your documentation site.
Difference from README.md
| Feature | docs/index.md |
README.md |
|---|---|---|
| Location | docs/ directory |
Project root |
| Purpose | Documentation homepage | Repository homepage |
| Header | "{project} Documentation" | "{project}" |
| Audience | Documentation readers | GitHub visitors |
| Content | Detailed docs structure | Quick overview |
Both files share the same badges and description, but serve different purposes.
Customization
You can add custom badges after the generated ones or add content after the
horizontal rules. To permanently change badge categories or order, subclass
BadgesMarkdownConfigFile and override the relevant methods.
If badges aren't rendering or content isn't updating, ensure your
pyproject.toml is correct and run uv run pyrig mkroot to regenerate.