vexy-mkdocs-output-as-input

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:

• ✅ Preserving your original Markdown structure and frontmatter
• ✅ Capturing the fully-rendered HTML output from MkDocs
• ✅ Creating new Markdown files that combine original metadata with processed HTML
• ✅ Enabling further processing by other static site generators

Installation

Install from PyPI:

uv pip install --system --upgrade vexy-mkdocs-output-as-input

Or install from source:

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:

plugins:
  - search  # Other plugins
  - output-as-input

Build your site:

mkdocs build

Find your processed files in the stage/ directory (relative to your MkDocs project root).

Configuration

All configuration options with their defaults:

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:

plugins:
  - output-as-input:
      html_element: [main, aside]  # Extract both main content and sidebar

Extract using CSS selectors:

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

• Input: Your source Markdown with frontmatter

  ---
  title: My Page
  author: Jane Doe
  ---
  
  # My Page
  
  This is my content with **markdown**.
  

• MkDocs Processing: Renders to HTML as usual

  <main class="md-content">
    <h1>My Page</h1>
    <p>This is my content with <strong>markdown</strong>.</p>
  </main>
  

• Output: Cousin file with preserved frontmatter + extracted HTML

  ---
  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:

# 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:

plugins:
  - output-as-input:
      html_element: article
      target_tag: div

🎨 Custom Post-Processing

Preserve MkDocs rendering while preparing for custom templates:

plugins:
  - output-as-input:
      stage_dir: _includes
      html_element: main
      target_tag: section

Examples

Basic Example

# mkdocs.yml
site_name: My Documentation
plugins:
  - output-as-input

Advanced Example

# 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:

#!/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

# 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

# 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

# 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.

• Fork the repository
• Create your feature branch (git checkout -b feature/AmazingFeature)
• Commit your changes (git commit -m 'Add some AmazingFeature')
• Push to the branch (git push origin feature/AmazingFeature)
• Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions