# vexy-mkdocs-output-as-input
[](https://pypi.org/project/vexy-mkdocs-output-as-input/)
[](https://github.com/vexyart/vexy-mkdocs-output-as-input/actions/workflows/ci.yml)
[](https://codecov.io/gh/vexyart/vexy-mkdocs-output-as-input)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/vexy-mkdocs-output-as-input/)
A MkDocs plugin that captures HTML output and creates "cousin" Markdown files with original frontmatter and extracted HTML content.
## Features
This plugin enables powerful post-processing workflows by:
1. ✅ Preserving your original Markdown structure and frontmatter
2. ✅ Capturing the fully-rendered HTML output from MkDocs
3. ✅ Creating new Markdown files that combine original metadata with processed HTML
4. ✅ Enabling further processing by other static site generators
## Installation
Install from PyPI:
```bash
uv pip install --system --upgrade vexy-mkdocs-output-as-input
```
Or install from source:
```bash
pip install git+https://github.com/vexyart/vexy-mkdocs-output-as-input
```
This also installs a CLI tool: `mkdocs-output-as-input`
## Quick Start
Add the plugin to your `mkdocs.yml`:
```yaml
plugins:
- search # Other plugins
- output-as-input
```
Build your site:
```bash
mkdocs build
```
Find your processed files in the `stage/` directory (relative to your MkDocs project root).
## Configuration
All configuration options with their defaults:
```yaml
plugins:
- output-as-input:
stage_dir: stage # Output directory name (default: 'stage')
html_element: main # HTML element to extract (default: 'main')
target_tag: article # Tag to use in output (default: 'article')
include_frontmatter: true # Include YAML frontmatter (default: true)
preserve_links: false # Convert absolute to relative links (default: false)
verbose: false # Enable verbose logging (default: false)
```
### Advanced Examples
Extract multiple elements:
```yaml
plugins:
- output-as-input:
html_element: [main, aside] # Extract both main content and sidebar
```
Extract using CSS selectors:
```yaml
plugins:
- output-as-input:
html_element: .content # Extract element with class="content"
```
### Options Explained
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `stage_dir` | string | `"stage"` | Directory name for output files (relative to project root) |
| `html_element` | string or list | `"main"` | CSS selector(s) for HTML elements to extract |
| `target_tag` | string | `"article"` | HTML tag to use in the output (replaces extracted element's tag) |
| `include_frontmatter` | boolean | `true` | Include YAML frontmatter in output files |
| `preserve_links` | boolean | `false` | Convert absolute links to relative (e.g., `/path` → `./path`) |
| `minify` | boolean | `false` | Minify HTML output (remove whitespace) |
| `prettify` | boolean | `false` | Prettify HTML output (add indentation) |
| `verbose` | boolean | `false` | Enable detailed logging for debugging |
## How It Works
### Input → Process → Output
1. **Input**: Your source Markdown with frontmatter
```markdown
---
title: My Page
author: Jane Doe
---
# My Page
This is my content with **markdown**.
```
2. **MkDocs Processing**: Renders to HTML as usual
```html
<main class="md-content">
<h1>My Page</h1>
<p>This is my content with <strong>markdown</strong>.</p>
</main>
```
3. **Output**: Cousin file with preserved frontmatter + extracted HTML
```markdown
---
title: My Page
author: Jane Doe
---
<article class="md-content">
<h1>My Page</h1>
<p>This is my content with <strong>markdown</strong>.</p>
</article>
```
## Use Cases
### 🔄 Multi-Stage Documentation Pipeline
Process documentation through MkDocs first, then feed to another SSG:
```yaml
# mkdocs.yml
plugins:
- output-as-input:
stage_dir: hugo/content
# Then run:
# mkdocs build && hugo build
```
### 📝 Content Extraction
Extract just the article content without theme wrapper:
```yaml
plugins:
- output-as-input:
html_element: article
target_tag: div
```
### 🎨 Custom Post-Processing
Preserve MkDocs rendering while preparing for custom templates:
```yaml
plugins:
- output-as-input:
stage_dir: _includes
html_element: main
target_tag: section
```
## Examples
### Basic Example
```yaml
# mkdocs.yml
site_name: My Documentation
plugins:
- output-as-input
```
### Advanced Example
```yaml
# mkdocs.yml
site_name: My Documentation
theme:
name: material
plugins:
- search
- output-as-input:
stage_dir: processed
html_element: article.md-content__inner
target_tag: main
verbose: true
# Process specific content area from Material theme
```
### Integration Example
Using with other tools in a documentation pipeline:
```bash
#!/bin/bash
# build.sh
# Stage 1: Build with MkDocs + plugins
mkdocs build
# Stage 2: Process staged output
python post_process.py stage/
# Stage 3: Build final site
hugo --contentDir=stage/
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/vexyart/vexy-mkdocs-output-as-input
cd vexy-mkdocs-output-as-input
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Install pre-commit hooks
pre-commit install
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=mkdocs_output_as_input --cov-report=html
# Run specific test
pytest tests/test_plugin.py::TestOutputAsInputPlugin::test_default_config
```
### Code Quality
```bash
# Format code
black src tests
# Lint code
ruff check src tests
# Type check
mypy src
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📧 Email: you@example.com
- 🐛 Issues: [GitHub Issues](https://github.com/vexyart/vexy-mkdocs-output-as-input/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/vexyart/vexy-mkdocs-output-as-input/discussions)
Raw data
{
"_id": null,
"home_page": null,
"name": "vexy-mkdocs-output-as-input",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Vexy Lines Team <help@vexy.art>",
"keywords": "documentation, html, markdown, mkdocs, plugin, postprocessing",
"author": null,
"author_email": "Vexy Lines Team <help@vexy.art>",
"download_url": "https://files.pythonhosted.org/packages/fe/dc/0b98339694746fd481c52a89d6138246e1ad06d79d272423094273f94061/vexy_mkdocs_output_as_input-1.0.9.tar.gz",
"platform": null,
"description": "# vexy-mkdocs-output-as-input\n\n[](https://pypi.org/project/vexy-mkdocs-output-as-input/)\n[](https://github.com/vexyart/vexy-mkdocs-output-as-input/actions/workflows/ci.yml)\n[](https://codecov.io/gh/vexyart/vexy-mkdocs-output-as-input)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/vexy-mkdocs-output-as-input/)\n\nA MkDocs plugin that captures HTML output and creates \"cousin\" Markdown files with original frontmatter and extracted HTML content.\n\n## Features\n\nThis plugin enables powerful post-processing workflows by:\n\n1. \u2705 Preserving your original Markdown structure and frontmatter\n2. \u2705 Capturing the fully-rendered HTML output from MkDocs\n3. \u2705 Creating new Markdown files that combine original metadata with processed HTML\n4. \u2705 Enabling further processing by other static site generators\n\n## Installation\n\nInstall from PyPI:\n\n```bash\nuv pip install --system --upgrade vexy-mkdocs-output-as-input\n```\n\nOr install from source:\n\n```bash\npip install git+https://github.com/vexyart/vexy-mkdocs-output-as-input\n```\n\nThis also installs a CLI tool: `mkdocs-output-as-input`\n\n## Quick Start\n\nAdd the plugin to your `mkdocs.yml`:\n\n```yaml\nplugins:\n - search # Other plugins\n - output-as-input\n```\n\nBuild your site:\n\n```bash\nmkdocs build\n```\n\nFind your processed files in the `stage/` directory (relative to your MkDocs project root).\n\n## Configuration\n\nAll configuration options with their defaults:\n\n```yaml\nplugins:\n - output-as-input:\n stage_dir: stage # Output directory name (default: 'stage')\n html_element: main # HTML element to extract (default: 'main')\n target_tag: article # Tag to use in output (default: 'article')\n include_frontmatter: true # Include YAML frontmatter (default: true)\n preserve_links: false # Convert absolute to relative links (default: false)\n verbose: false # Enable verbose logging (default: false)\n```\n\n### Advanced Examples\n\nExtract multiple elements:\n```yaml\nplugins:\n - output-as-input:\n html_element: [main, aside] # Extract both main content and sidebar\n```\n\nExtract using CSS selectors:\n```yaml\nplugins:\n - output-as-input:\n html_element: .content # Extract element with class=\"content\"\n```\n\n### Options Explained\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `stage_dir` | string | `\"stage\"` | Directory name for output files (relative to project root) |\n| `html_element` | string or list | `\"main\"` | CSS selector(s) for HTML elements to extract |\n| `target_tag` | string | `\"article\"` | HTML tag to use in the output (replaces extracted element's tag) |\n| `include_frontmatter` | boolean | `true` | Include YAML frontmatter in output files |\n| `preserve_links` | boolean | `false` | Convert absolute links to relative (e.g., `/path` \u2192 `./path`) |\n| `minify` | boolean | `false` | Minify HTML output (remove whitespace) |\n| `prettify` | boolean | `false` | Prettify HTML output (add indentation) |\n| `verbose` | boolean | `false` | Enable detailed logging for debugging |\n\n## How It Works\n\n### Input \u2192 Process \u2192 Output\n\n1. **Input**: Your source Markdown with frontmatter\n ```markdown\n ---\n title: My Page\n author: Jane Doe\n ---\n \n # My Page\n \n This is my content with **markdown**.\n ```\n\n2. **MkDocs Processing**: Renders to HTML as usual\n ```html\n <main class=\"md-content\">\n <h1>My Page</h1>\n <p>This is my content with <strong>markdown</strong>.</p>\n </main>\n ```\n\n3. **Output**: Cousin file with preserved frontmatter + extracted HTML\n ```markdown\n ---\n title: My Page\n author: Jane Doe\n ---\n \n <article class=\"md-content\">\n <h1>My Page</h1>\n <p>This is my content with <strong>markdown</strong>.</p>\n </article>\n ```\n\n## Use Cases\n\n### \ud83d\udd04 Multi-Stage Documentation Pipeline\n\nProcess documentation through MkDocs first, then feed to another SSG:\n\n```yaml\n# mkdocs.yml\nplugins:\n - output-as-input:\n stage_dir: hugo/content\n\n# Then run:\n# mkdocs build && hugo build\n```\n\n### \ud83d\udcdd Content Extraction\n\nExtract just the article content without theme wrapper:\n\n```yaml\nplugins:\n - output-as-input:\n html_element: article\n target_tag: div\n```\n\n### \ud83c\udfa8 Custom Post-Processing\n\nPreserve MkDocs rendering while preparing for custom templates:\n\n```yaml\nplugins:\n - output-as-input:\n stage_dir: _includes\n html_element: main\n target_tag: section\n```\n\n## Examples\n\n### Basic Example\n\n```yaml\n# mkdocs.yml\nsite_name: My Documentation\nplugins:\n - output-as-input\n```\n\n### Advanced Example\n\n```yaml\n# mkdocs.yml\nsite_name: My Documentation\ntheme:\n name: material\n\nplugins:\n - search\n - output-as-input:\n stage_dir: processed\n html_element: article.md-content__inner\n target_tag: main\n verbose: true\n\n# Process specific content area from Material theme\n```\n\n### Integration Example\n\nUsing with other tools in a documentation pipeline:\n\n```bash\n#!/bin/bash\n# build.sh\n\n# Stage 1: Build with MkDocs + plugins\nmkdocs build\n\n# Stage 2: Process staged output\npython post_process.py stage/\n\n# Stage 3: Build final site\nhugo --contentDir=stage/\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/vexyart/vexy-mkdocs-output-as-input\ncd vexy-mkdocs-output-as-input\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .[dev]\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=mkdocs_output_as_input --cov-report=html\n\n# Run specific test\npytest tests/test_plugin.py::TestOutputAsInputPlugin::test_default_config\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src tests\n\n# Lint code\nruff check src tests\n\n# Type check\nmypy src\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: you@example.com\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/vexyart/vexy-mkdocs-output-as-input/issues)\n- \ud83d\udcac Discussions: [GitHub Discussions](https://github.com/vexyart/vexy-mkdocs-output-as-input/discussions)",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin that captures HTML output and creates cousin Markdown files with original frontmatter",
"version": "1.0.9",
"project_urls": {
"Changelog": "https://github.com/vexyart/vexy-mkdocs-output-as-input/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/vexyart/vexy-mkdocs-output-as-input",
"Homepage": "https://github.com/vexyart/vexy-mkdocs-output-as-input",
"Issues": "https://github.com/vexyart/vexy-mkdocs-output-as-input/issues",
"Repository": "https://github.com/vexyart/vexy-mkdocs-output-as-input"
},
"split_keywords": [
"documentation",
" html",
" markdown",
" mkdocs",
" plugin",
" postprocessing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aa465bf655d15965f9881a282c17145f0de7e426f28ed19b0e132d01c2f3f8a9",
"md5": "fbfdaca175ba564ef05a6ccbd625b922",
"sha256": "2a391479c0be6cee64ccbdb4c8afc83693075c37c1cc26241cbb4b409b7b19ed"
},
"downloads": -1,
"filename": "vexy_mkdocs_output_as_input-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fbfdaca175ba564ef05a6ccbd625b922",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11788,
"upload_time": "2025-07-15T00:42:06",
"upload_time_iso_8601": "2025-07-15T00:42:06.907346Z",
"url": "https://files.pythonhosted.org/packages/aa/46/5bf655d15965f9881a282c17145f0de7e426f28ed19b0e132d01c2f3f8a9/vexy_mkdocs_output_as_input-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fedc0b98339694746fd481c52a89d6138246e1ad06d79d272423094273f94061",
"md5": "f12c0654ad4168440effd41508038060",
"sha256": "f46bc8cd57f98688ddff5e31d7ba2a1ec46dec04effb967d655278815d29120b"
},
"downloads": -1,
"filename": "vexy_mkdocs_output_as_input-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "f12c0654ad4168440effd41508038060",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15430,
"upload_time": "2025-07-15T00:42:05",
"upload_time_iso_8601": "2025-07-15T00:42:05.597911Z",
"url": "https://files.pythonhosted.org/packages/fe/dc/0b98339694746fd481c52a89d6138246e1ad06d79d272423094273f94061/vexy_mkdocs_output_as_input-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 00:42:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vexyart",
"github_project": "vexy-mkdocs-output-as-input",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vexy-mkdocs-output-as-input"
}
JSON
