The Architecture of Better Documentation.

Markitecture: The Python toolkit that empowers modular Markdown workflows.

What is Markitecture?

Markitecture is a comprehensive Python toolkit designed to streamline your Markdown workflow. Whether you're managing documentation, writing technical content, or maintaining a knowledge base, Markitecture provides essential utilities to make working with Markdown files easier and more efficient.

Key Features

• Text Splitting: Break down large Markdown files into manageable sections based on headings or custom rules.
• Link Management: Convert between inline and reference-style links, validate URLs, and identify broken links.
• Content Analysis: Analyze document structure, extract metadata, and ensure consistent formatting.
• Documentation Tools: Generate configurations for static site generators like MkDocs.

---

Quick Start

Installation

Install from PyPI using your preferred package manager.

 pip

Use pip (recommended for most users):

pip install -U markitecture

 pipx

Install in an isolated environment with pipx:

❯ pipx install markitecture

 uv

For the fastest installation use uv:

❯ uv tool install markitecture

Using the CLI

Text Splitting

Split large Markdown files into smaller, organized sections:

markitect \
    --split.i tests/data/readme-ai.md \
    --split.o examples/split-sections-h2

Link Validation

Check for broken links in your documentation:

markitect --check-links.input tests/data/pydantic.md

In your terminal, you'll see a summary of the results:

Markdown Link Check Results

┏━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Status ┃ Line ┃ Link                                                                              ┃ Error    ┃
┡━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ ✓      │ 2    │ https://img.shields.io/github/actions/workflow/status/pydantic/pydantic/ci.yml?b… │          │
│ ✓      │ 3    │ https://coverage-badge.samuelcolvin.workers.dev/pydantic/pydantic.svg             │          │
│ ✓      │ 4    │ https://img.shields.io/pypi/v/pydantic.svg                                        │          │
│ ✓      │ 5    │ https://img.shields.io/conda/v/conda-forge/pydantic.svg                           │          │
│ ✓      │ 6    │ https://static.pepy.tech/badge/pydantic/month                                     │          │
│ ✓      │ 7    │ https://img.shields.io/pypi/pyversions/pydantic.svg                               │          │
│ ✓      │ 8    │ https://img.shields.io/github/license/pydantic/pydantic.svg                       │          │
│ ✓      │ 9    │ https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/p… │          │
│ ✓      │ 18   │ https://pydantic.dev/articles/logfire-announcement                                │          │
│ ✓      │ 24   │ https://docs.pydantic.dev/                                                        │          │
│ ✓      │ 24   │ https://github.com/pydantic/pydantic/tree/1.10.X-fixes                            │          │
│ ✓      │ 28   │ https://docs.pydantic.dev/                                                        │          │
│ 𝗫      │ 34   │ https://docs.pydantic.dev/install/invalid-link                                    │ HTTP 404 │
└────────┴──────┴───────────────────────────────────────────────────────────────────────────────────┴──────────┘

Summary: 1 broken links out of 13 total links.

Reference Link Conversion

In Markdown, reference-style links let you write cleaner text by keeping URLs in a reference section - think footnotes for the web.

To convert inline links to reference-style links:

markitect \
    --reflinks.input tests/data/pydantic.md \
    --reflinks.output with_refs.md

Static Site Configuration Generation

Generate a MkDocs configuration (mkdocs.yml) from a given Markdown file.

1. Split the Markdown file into sections:

   markitect \
       --split.i tests/data/readme-ai.md \
       --split.o examples/split-sections-h2

2. Generate the MkDocs configuration:

   markitect \
       --mkdocs.dir examples/split-sections-h2 \
       --mkdocs.site-name "MyDocsSite"

See additional example and usage details in the here.

---

Roadmap

• Support for additional documentation formats (e.g., reStructuredText, HTML)
• Enhanced link management utilities
• Improved content analysis features
• Integration with more static site generators
• Plugin system for custom utilities
• More intuitive CLI commands and options

---

Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or code contributions, please feel free to:

• Open an issue
• Submit a pull request
• Improve documentation, write tutorials, etc.
• Share your feedback and suggestions

---

License

Copyright © 2024-2025 Markitecture.
Released under the MIT license.