serve-md-by-mkdocs

Serve scattered Markdown documents via MkDocs while preserving directory structure.

7|1|Updated Jul 10, 2025

Search Tags:#markdown #scaffold #docs #mkdocs #viewer #serve

Ready to run

npx skills add https://github.com/igamenovoer/magic-context --skill serve-md-by-mkdocs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: serve-md-by-mkdocs
Source: https://github.com/igamenovoer/magic-context/tree/main/skills/devel/serve-md-by-mkdocs
Command: npx skills add https://github.com/igamenovoer/magic-context --skill serve-md-by-mkdocs

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill provides a quick, web-based viewer for Markdown scattered across a repository by serving them with MkDocs while preserving the original directory structure.

Core Features & Use Cases

Web-based Markdown viewer: browse notes, runbooks, and docs across a project without moving files.
Dedicated work directory scaffolding: auto-create a scanner, manifest, and a generated mkdocs.yml (preserving existing config when available).
Built-in MkDocs integration: Mermaid and KaTeX support via pymdown-extensions, with a simple path for serving locally.
Use Case: quickly preview scattered documentation in a large codebase without reorganizing assets or writing custom docs nav.

Quick Start

Run the workflow to scaffold the docview service and start MkDocs serve:

Create or reuse a work directory and run the refresh-docs-tree.sh to build the staged tree.
Start MkDocs: mkdocs serve -f <work_dir>/mkdocs.yml

Frequently Asked Questions about serve-md-by-mkdocs

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I serve Markdown files across a repository with MkDocs without moving them?▼

You can serve Markdown files scattered across a repository with MkDocs by scaffolding a dedicated work directory. This generates a scanner and manifest to build a staged tree, preserving your original directory structure while providing a web-based viewer.

What is the best way to preview scattered documentation in a large codebase?▼

The best way to preview scattered documentation is using a web-based viewer that auto-discovers Markdown assets and generates a manifest. This serves your notes and runbooks locally without reorganizing files or writing custom docs navigation.

Do I need an existing MkDocs installation to use this Markdown viewer?▼

Yes, you need an existing MkDocs installation in your environment to use this Markdown viewer. The skill uses Python scripts to scaffold the service and generate an mkdocs.yml file, which requires the core MkDocs engine to serve locally.

Does this MkDocs viewer support Mermaid diagrams and KaTeX math formulas?▼

Yes, this MkDocs viewer supports Mermaid diagrams and KaTeX math formulas via pymdown-extensions. These built-in integrations are included when the service scaffolds the generated mkdocs.yml configuration file.

How do I start the local MkDocs server after generating the documentation tree?▼

To start the local MkDocs server, run the refresh-docs-tree.sh script to build the staged tree, then execute mkdocs serve with the generated configuration file path pointing to your work directory.

What happens to my existing mkdocs.yml configuration when scaffolding the viewer?▼

When scaffolding the viewer, the service preserves your existing mkdocs.yml configuration when available. It generates a dedicated configuration file in the work directory to serve the discovered Markdown assets without overwriting your original setup.