emdg
emdg (Easy Markdown Docs Generator) scans Markdown files and builds a single
HTML documentation site. It uses convention over configuration: folders become
sections, filenames become page titles, and optional frontmatter customizes
pages and sections.
Features
- One command to build a searchable, hash-routed documentation site.
- Nested folders become nested sidebar sections.
- Optional frontmatter for page titles, order, descriptions, tags, drafts, and section metadata.
- Light, dark, and system-preference themes.
- Optional local HTTP server and automatic rebuild mode.
- No third-party Python runtime dependencies.
Requirements and installation
Python 3.13 or newer is required.
Install the published package:
pip install emdg
Then run it from any directory:
emdg --help
To install an editable checkout with the test dependency:
python -m pip install -e ".[test]"
AI agent skill
The emdg documentation skill guides AI agents in organizing docs and using the CLI, including frontmatter and build workflows.
Quick start
Given a project like:
my-project/
├── docs/
│ ├── overview.md
│ ├── getting-started/
│ │ ├── _section.md
│ │ ├── install.md
│ │ └── first-steps.md
│ └── reference/
│ └── commands.md
└── ...
Build the site:
emdg docs
This scans docs/ and writes docs.html to the current working directory.
The output location is independent of the source directory. Root-level Markdown
files appear first in the sidebar, except for a root-level README.md: it is
the site's home page, opens by default, and is omitted from the sidebar. Clicking
the site title returns to that page. Folders become sections, with deeper folders
becoming subsections.
The page title defaults to the source directory name (docs becomes Docs).
Filenames and folder names are humanized by replacing hyphens and underscores
with spaces and capitalizing words (getting-started becomes Getting Started).
Frontmatter can override a Markdown page's display title.
Command-line reference
emdg [source] [-o OUTPUT] [-t TITLE] [-i NAME]... [--theme auto|light|dark]
[--serve] [--watch] [-v]
| Option | Default | Description |
|---|---|---|
source |
. |
Directory to scan recursively. It must exist and be a directory. |
-o, --output |
docs.html |
Output HTML file. Relative paths are resolved from the current working directory; its parent directory must already exist. |
-t, --title |
Humanized source directory name | Site title shown in the browser tab and interface. |
-i, --ignore NAME |
Built-in ignores | Ignore a file or directory by name. Repeat the option for multiple names. Names are matched anywhere in the source tree, not as paths. |
--theme |
auto |
Initial theme: auto follows the browser's system preference, or choose light or dark. A theme already saved in that browser takes precedence. |
--serve |
Off | Serve the generated output on http://127.0.0.1:8000/<output-filename> until interrupted. |
--watch |
Off | Keep running and rebuild after Markdown files are added, removed, or changed. |
-v, --verbose |
Off | Print informational messages, including build and watch activity. |
-h, --help |
— | Show command help. |
Examples:
# Use the current directory and default output
emdg
# Give the site a name and choose the output path
emdg ./docs --output ./public/manual.html --title "Team Handbook"
# Exclude matching names wherever they occur in the source tree
emdg docs --ignore internal --ignore drafts
# Build using a light theme
emdg docs --theme light
# Serve the generated docs and rebuild when Markdown changes
emdg docs --output site.html --serve --watch
The server binds to loopback (127.0.0.1) on fixed port 8000; it is intended
for local preview, not as a public hosting server. Without --watch, --serve
serves the one build made when the command starts. With --watch, the CLI checks
for Markdown file changes about twice per second and rebuilds the same output.
Press Ctrl+C to stop serving or watching.
The built-in ignored directory names are .git, .hg, .svn, .venv, venv,
__pycache__, node_modules, .idea, .vscode, dist, and build. Any
dot-prefixed file or directory is also ignored automatically. Custom ignores
are additional name matches; they do not enable scanning hidden files.
The CLI scans .md files (case-insensitively). The Python scanning API can use
other extensions.
Optional frontmatter
Frontmatter is a small YAML-like block at the very top of a Markdown file. It
starts with a line containing --- and ends with a line containing --- or
.... Everything after the closing line is the Markdown body; the delimiters
are removed before rendering.
---
title: Cursor Pagination
emoji: 📄
order: 2
description: How cursor-based pagination works across endpoints.
tags: [api, pagination]
draft: false
---
# Cursor Pagination
Write the page content here.
All fields are optional. Without frontmatter, the file is still included and its title is derived from its filename.
| Field | Type and default | Effect |
|---|---|---|
title |
Text; filename-derived title | Overrides the page's sidebar label. It does not add a heading to the Markdown body. |
emoji |
Text; none | Prefixes the page's sidebar label. |
order |
Integer; 999 |
Sorts pages or sections numerically in ascending order. Equal orders are sorted by title, case-insensitively, then by relative path. Lower numbers appear first; omitted or invalid values use 999. |
description |
Text; none | Displays a short description above the page body. |
tags |
List of text; empty list | Displays tag badges and includes each tag in sidebar search. |
draft |
Boolean-like text; false |
Excludes the page from the generated site when set to a recognized true value. |
Frontmatter value syntax
This is a deliberately small parser, not a full YAML implementation:
-
Values can be unquoted, single-quoted, or double-quoted. Matching outer quotes are removed; YAML escape sequences and nested objects are not parsed.
-
ordermust be an integer. A non-integer value leaves the default order (999) in effect. -
draft: true,draft: yes,draft: 1, anddraft: onare treated as true, case-insensitively. Other values, includingfalse, are false. -
Tags can be written inline or as a block list:
tags: [api, "getting started"]
tags: - api - getting started
-
Blank lines and lines beginning with
#inside the frontmatter are ignored. -
Unknown keys are accepted by the parser but do not change the generated documentation.
-
If the opening delimiter is missing or there is no closing delimiter, the content is treated as ordinary Markdown instead of being partially removed.
Section metadata files
To customize a folder's sidebar section, put _section.md or index.md in that
folder and add frontmatter:
docs/
└── getting-started/
├── _section.md
├── install.md
└── first-steps.md
---
title: Start Here
emoji: 🚀
order: 1
description: Installation and first steps.
---
# Start Here
This content appears when the section is selected.
The title, emoji, and order values customize the section's sidebar label
and position. _section.md takes precedence over index.md if both exist.
These helper files are reserved and are not rendered as pages; an index.md
body is not used as a landing page. Markdown after _section.md's frontmatter
is displayed as the section's landing content when its sidebar heading is
selected. If _section.md has no body, the heading only expands the navigation.
A section's frontmatter description is shown above its landing content when
present. A folder is shown only when it contains at least one non-draft
Markdown page somewhere below it.
Generated site behavior
- The output is one HTML file containing the scanned Markdown content and client-side page data. Navigation changes the URL hash; it does not fetch Markdown files after generation.
- The sidebar search filters on page title, Markdown body text, and tags.
- Sidebar sections and subsections are collapsible and start closed. The section containing the current page opens automatically; searching opens sections with matching results.
- If a section has Markdown body content in
_section.md, selecting its heading displays that content in the main pane as a section landing page. - The home page footer shows when the site was generated, using a UTC timestamp.
- Pages with
##or###headings get an automatic "On this page" table of contents with in-page links. - GitHub-style blockquote callouts are supported:
[!NOTE],[!TIP],[!IMPORTANT],[!WARNING], and[!CAUTION]. Their styling and the table of contents are implemented inline; they add no CDN dependencies. - The selected page's description and tags appear above its content.
- A saved theme choice is kept in browser
localStorageunderemdg-theme. This saved choice takes precedence over the generated--themedefault. - Standard Markdown is rendered in the browser by Marked. Fenced code blocks
are highlighted by Highlight.js;
mermaidfenced blocks are rendered as diagrams by Mermaid. - Tailwind CSS, Marked, Highlight.js, and Mermaid load from public CDNs. An internet connection is required for the complete styling and rendering experience.
- The Markdown renderer supports raw HTML. Only build and publish documentation from sources you trust.
Python API
from emdg import generate_html, scan_docs
result = scan_docs(
"docs",
ignore={"internal"},
extensions={".md", ".markdown"},
)
output = generate_html(
result,
"public/docs.html",
title="Team Handbook",
theme="dark",
)
print(output)
scan_docs
scan_docs(origin, *, ignore=None, extensions=(".md",))
originis a directory path (strorpathlib.Path).ignoreis an optional iterable of exact file/directory names to exclude. Built-in ignores and the automatic dotfile exclusion still apply.extensionsis an iterable of extensions, with or without the leading dot. Matching is case-insensitive.- Returns a
ScanResultwith an optional roothomepage, otherroot_items, and nestedsections. A root-levelREADME.mdbecomeshomeand is not included inroot_items; a README inside a section remains a normal page. - Each
DocItemstores its title, slug, absolute file path, relative path, emoji, order, description, and tags. EachDocSectionstores the section metadata, optional Markdown body, items, and subsections. - Raises
FileNotFoundErrorif the origin does not exist andNotADirectoryErrorif it is not a directory.
generate_html
generate_html(scan_result, output_path="docs.html", *, title=None, theme="auto")
scan_resultis the result ofscan_docs.output_pathis the HTML file path; its parent directory must exist.titleoverrides the site title. By default, the scan root's directory name is humanized.thememust beauto,light, ordark.- Writes UTF-8 HTML and returns the resolved output
Path.
The public package also exports Frontmatter, DocItem, DocSection,
ScanResult, parse_frontmatter, and humanize_name.
Development
Install the optional test dependency and run the test suite:
python -m pip install -e ".[test]"
python -m pytest
Metadata
Release files for emdg 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| emdg-0.2.0.tar.gz | 28.7 kB | With provenance | Details for emdg-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| emdg-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for emdg-0.2.0-py3-none-any.whl |
Total release size: 49.4 kB
Release files / emdg-0.2.0.tar.gz
| Download URL | emdg-0.2.0.tar.gz |
|---|---|
| Size | 28.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
486e126d13f6aae39c3e2900271d2246a2e674ec82aca347e5c9971cab7971a3
|
|
BLAKE2b-256 checksum How to use checksums |
dbedfacba35a167830e70e8b518165ff4b1fa6d4dec3ce3dc257df252c55dcec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / emdg-0.2.0-py3-none-any.whl
| Download URL | emdg-0.2.0-py3-none-any.whl |
|---|---|
| Size | 20.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f4a5872f8f0e46a5f6e85e8e3a7a09252ae5a5332c0bf60a3c91c2c46273cdb4
|
|
BLAKE2b-256 checksum How to use checksums |
914f72d05a3edeb9966c4d660fb3feac700d296eddf48c3b9e761703f1b3fff1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for emdg 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for emdg-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.