https://github.com/eli64s/markitecture
❂ Tools for modular and flexible Markdown docs: link validation, reference-style link converter, text splitting, static site generation, & more.
https://github.com/eli64s/markitecture
ai content-management devtools docs documentation documentation-tool link-checker link-validator markdown markdown-parser markdown-split markdown-tools mkdocs python reference-links reflinks
Last synced: 3 months ago
JSON representation
❂ Tools for modular and flexible Markdown docs: link validation, reference-style link converter, text splitting, static site generation, & more.
- Host: GitHub
- URL: https://github.com/eli64s/markitecture
- Owner: eli64s
- License: mit
- Created: 2024-06-07T05:55:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-24T07:40:52.000Z (12 months ago)
- Last Synced: 2025-01-24T08:28:12.560Z (12 months ago)
- Topics: ai, content-management, devtools, docs, documentation, documentation-tool, link-checker, link-validator, markdown, markdown-parser, markdown-split, markdown-tools, mkdocs, python, reference-links, reflinks
- Language: Python
- Homepage:
- Size: 344 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
)
Markitecture
The Architecture of Better Documentation.
Tools for modular Markdown workflows and content management.
[Documentation][markitecture] · [Contribute][contributing] · [Report Bug][github-issues] · [Request Feature][github-issues]
## 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][mkdocs].
---
## Quick Start
### Installation
Install from [PyPI][pypi] using your preferred package manager.
#### 
 pip
Use [pip][pip] (recommended for most users):
```sh
pip install -U markitecture
```
#### 
 pipx
Install in an isolated environment with [pipx][pipx]:
```sh
❯ pipx install markitecture
```
#### 
 uv
For the fastest installation use [uv][uv]:
```sh
❯ uv tool install markitecture
```
### Using the CLI
#### Text Splitting
Split large Markdown files into smaller, organized sections:
```sh
markitect \
--split.i tests/data/readme-ai.md \
--split.o examples/split-sections-h2
```
#### Link Validation
Check for broken links in your documentation:
```sh
markitect --check-links.input tests/data/pydantic.md
```
In your terminal, you'll see a summary of the results:
```console
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][reflinks] 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:
```sh
markitect \
--reflinks.input tests/data/pydantic.md \
--reflinks.output with_refs.md
```
#### Static Site Configuration Generation
Generate a MkDocs configuration [(mkdocs.yml)][mkdocs.yml] from a given Markdown file.
1. Split the Markdown file into sections:
```sh
markitect \
--split.i tests/data/readme-ai.md \
--split.o examples/split-sections-h2
```
2. Generate the MkDocs configuration:
```sh
markitect \
--mkdocs.dir examples/split-sections-h2 \
--mkdocs.site-name "MyDocsSite"
```
See additional example and usage details in the [here][examples].
---
## 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][github-issues]
- Submit a [pull request][github-pulls]
- Improve documentation, write tutorials, etc.
- Share your feedback and suggestions
---
## License
Copyright © 2024-2025 [Markitecture][markitecture].
Released under the [MIT][mit-license] license.
[![][return-to-top]](#top)
[return-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-7934C5?style=flat-square
[pypi]: https://pypi.org/project/markitecture/
[markitecture]: https://github.com/eli64s/markitecture
[github-issues]: https://github.com/eli64s/markitecture/issues
[github-pulls]: https://github.com/eli64s/markitecture/pulls
[contributing]: https://github.com/eli64s/markitecture/blob/main/CONTRIBUTING.md
[mit-license]: https://github.com/eli64s/markitecture/blob/main/LICENSE
[examples]: https://github.com/eli64s/markitecture/tree/main/examples
[python]: https://www.python.org/
[pip]: https://pip.pypa.io/en/stable/
[pipx]: https://pipx.pypa.io/stable/
[uv]: https://docs.astral.sh/uv/
[mkdocs]: https://www.mkdocs.org/
[mkdocs.yml]: https://www.mkdocs.org/user-guide/configuration/
[reflinks]: https://www.markdownguide.org/basic-syntax/#reference-style-links