md-html-docs

Convert any markdown file to styled, self-contained HTML. Auto-detects language and picks the right template.

When this skill is invoked (manually or via hook), print the version banner:

md-html-docs v{version} | Released: {released}

Read version and released from this file's YAML frontmatter.

How It Works

The plugin includes a self-contained Python converter (convert.py) with zero dependencies. It:

1. Parses markdown using regex (headings, bold/italic, code blocks, tables, lists, blockquotes, checkboxes, links, images, HR, diagrams)
2. Detects Hebrew content (>5% Hebrew characters) → uses RTL template with Heebo font
3. English/other content → uses LTR template with Inter font
4. Extracts title from first # heading, subtitle from next heading/blockquote/paragraph
5. Generates sidebar TOC from h2/h3 headings
6. Generates index.html for folders listing documents and subfolders

Locating convert.py

CRITICAL: Always derive the converter path from this skill's base directory. The converter lives at ../../convert.py relative to this SKILL.md file.

CONVERTER="${SKILL_BASE_DIR}/../../convert.py"

Where SKILL_BASE_DIR is the "Base directory for this skill" shown at the top when this skill is loaded. For example, if the base directory is: ~/.claude/plugins/cache/moonsite-claude-extensions/md-html-docs/2.5.1/skills/md-html-docs

Then the converter path is: ~/.claude/plugins/cache/moonsite-claude-extensions/md-html-docs/2.5.1/convert.py

NEVER hardcode a version number in the path. Always resolve from the skill's own base directory to ensure you use the currently installed version.

Workflow

When a .md file is created or edited:

1. The PostToolUse hook automatically runs the converter on the file
2. The hook also regenerates the parent folder's index.html
3. No manual action needed (if auto-generation is enabled)

For manual conversion:

Run the converter directly using the resolved path:

python3 "$CONVERTER" path/to/file.md            # single file
python3 "$CONVERTER" path/to/folder/             # folder (non-recursive)
python3 "$CONVERTER" --all docs/                 # recursive + all indexes
python3 "$CONVERTER" --index docs/guides/        # regenerate index only

Enable/disable auto-generation:

/md-html-docs enable    # turn on auto-generation
/md-html-docs disable   # turn off
/md-html-docs status    # check current state

Document Metadata

YAML Frontmatter (per-file)

Add frontmatter to any .md file to control its title, description, icon, and accent color in index pages:

---
title: My Document Title
description: Brief description shown on index cards
icon: 📊
accent: purple
---

# Actual content starts here...

Supported fields: title, description, icon (emoji), accent (blue, green, purple, orange).

Frontmatter is stripped from the rendered HTML — it only affects metadata.

Project Config (.claude/md-html-docs.json)

IMPORTANT — set this up before generating HTML. Create .claude/md-html-docs.json in the project root:

{
  "projectName": "Brosh",
  "orgName": "Moonsite",
  "logoText": "BR",
  "colorScheme": "blue",
  "footerText": "Brosh Documentation",
  "documents": {
    "intro.md": { "title": "Getting Started", "icon": "🚀", "accent": "green" }
  },
  "folders": {
    "specs": { "title": "Technical Specs", "icon": "📐" }
  }
}

Header Layout

The sticky header displays these config values:

[logo circle] [project name]  [doc title]  ...  [Index btn] [Layout buttons]
              [org name]

Config Field	Where It Shows	Example	Notes
projectName	Header — main label (bold)	"Brosh"	Product/project name
orgName	Header — subtitle below project name	"Moonsite"	Company/team. Leave empty "" to hide
logoText	Header — 2-char circle icon	"BR"	Auto-derived from first 2 chars of projectName if omitted

If projectName and orgName show the same value, one of them is wrong. projectName = the product/project, orgName = the company/team that owns it. Set orgName to "" to hide it entirely.

All Config Fields

• projectName — required — product/project name shown in header
• orgName — company/team name shown below project name (set "" to hide)
• logoText — 2-char text in header circle (auto-derived from projectName if omitted)
• colorScheme — preset theme: blue, green, purple, orange
• accentColor, headerFrom, headerTo — custom hex colors (override preset)
• footerText — custom footer text
• documents — per-file overrides keyed by filename: {"file.md": {title, description, icon, accent}}
• folders — per-folder overrides keyed by folder name: {"guides": {title, description, icon, accent}}

Priority chain: config documents/folders override > frontmatter > auto-extracted from headings.

Links Between Documents

Local .md links are automatically rewritten to .html during conversion:

See [the API docs](api.md) or [setup guide](guides/setup.md#configuration)

Becomes: <a href="api.html"> and <a href="guides/setup.html#configuration">.

Enriching Index Pages (MANDATORY)

CRITICAL: NEVER leave index pages with raw folder names or generic "documents N" descriptions. After ANY conversion (--all, folder, or single file), you MUST enrich ALL index pages so every item has:

• A human-readable title (not raw folder/file name)
• A meaningful description (1 sentence summarizing content)
• An icon (emoji that represents the content)

This applies to BOTH folders AND documents in every index page.

How to enrich:

1. Read content: For each .md file, read the first heading and first paragraph. For each folder, read the headings of its .md files to understand the section's purpose.

2. Update config: Write/update .claude/md-html-docs.json with enriched metadata for ALL folders and documents:

{
  "projectName": "My Project",
  "orgName": "Company Name",
  "logoText": "MP",
  "colorScheme": "blue",
  "footerText": "My Project Documentation",
  "folders": {
    "brosh": { "title": "ברוש — פורטל מימון", "description": "מסמכי אפיון, דרישות מערכת וארכיטקטורה", "icon": "🏗️" },
    "common": { "title": "מסמכים משותפים", "description": "תשתית, API ותיעוד טכני כללי", "icon": "📚" },
    "mock": { "title": "נתוני בדיקה", "description": "מערכת Mock ונתוני דמה לפיתוח", "icon": "🧪" }
  },
  "documents": {
    "requirements-spec.md": { "title": "דרישות מערכת (FRS)", "description": "דרישות פונקציונליות, מסכי UI, תהליכים עסקיים", "icon": "📋" },
    "api-reference.md": { "title": "API Reference", "description": "תיעוד Endpoints מלא — הזדהות, עסקאות, רכבים", "icon": "🔌" }
  }
}

3. Add YAML frontmatter to .md files that don't have it:

---
title: Developer Guide
description: Hands-on guide for integrating AI tools into daily development workflow
icon: 💻
---

4. Regenerate: run the converter with --all to rebuild all indexes with the enriched metadata.

Bad vs Good index cards:

BAD (never do this):

brosh          | documents 5
common         | documents 8
mock           | document 1

GOOD (always do this):

🏗️ ברוש — פורטל מימון      | מסמכי אפיון, דרישות מערכת וארכיטקטורה
📚 מסמכים משותפים            | תשתית, API ותיעוד טכני כללי
🧪 נתוני בדיקה               | מערכת Mock ונתוני דמה לפיתוח

When to enrich: ALWAYS. Every time --all is run or a new folder/file is created. Never leave raw names.

Exclude Files (.md-html-docs-ignore)

Place a .md-html-docs-ignore file at the project root to exclude files and folders from conversion. Format is like .gitignore:

# Comments start with #
drafts/              # Skip entire directory
internal/            # Another directory to skip
secret-*.md          # Glob pattern for filenames
specs/old/**         # Everything under specs/old
!drafts/important.md # Re-include a specific file (negation)

The converter also has built-in exclusions for: node_modules, .venv, venv, __pycache__, .git, dist, .tox, .mypy_cache, .pytest_cache, env, .env.

Key Rules

• Never edit .html files directly — always edit .md and let the converter regenerate
• Commit .md and .html together — never commit one without the other
• Images: reference with relative paths in markdown, e.g. ![alt](images/screenshot.png)
• Templates are auto-selected — Hebrew content gets RTL, everything else gets LTR
• Diagram blocks (mermaid, pintora, dot, graphviz, nomnoml, d2) render as interactive SVGs via client-side libraries (d2 uses Kroki.io API)
• Review notes: heading 📝 buttons and text-selection notes are stored in localStorage per page; export to Markdown groups notes by section