mintlify-docs-updater

Mintlify Docs Updater

Overview

Use this skill to ingest user-provided Markdown into the Mintlify docs tree, enforce required frontmatter, and update navigation entries in docs/docs.json. Prefer the included script for deterministic page placement and nav updates.

Workflow

1. Read the current site map in references/docs-structure.md.
2. Decide the destination page path (for example, core/new-feature -> docs/core/new-feature.md).
3. Ingest the uploaded Markdown file with the script:

python3 scripts/ingest_markdown_doc.py \
  --source /absolute/path/to/upload.md \
  --page core/new-feature \
  --group "Core"

1. Use --subgroup "Models" when adding pages under core/models.
2. Use --dry-run first when the target placement is uncertain.
3. Validate changes:
   • Confirm the new file exists under docs/.
   • Confirm docs/docs.json includes the new "/path/to/page" entry in the right group.
   • Confirm frontmatter includes title and description.

Commands

Add a new page and nav entry:

python3 scripts/ingest_markdown_doc.py \
  --source /absolute/path/to/upload.md \
  --page get_started/advanced-setup \
  --group "Get Started"

Add a new Core > Models page and place it after an existing page:

python3 scripts/ingest_markdown_doc.py \
  --source /absolute/path/to/model-guide.md \
  --page core/models/new-provider \
  --group "Core" \
  --subgroup "Models" \
  --insert-after /core/models/kimi

Preview changes without writing files:

python3 scripts/ingest_markdown_doc.py \
  --source /absolute/path/to/upload.md \
  --page troubleshooting/new-issue \
  --group "Troubleshooting" \
  --dry-run

Editing Rules

1. Keep page files in docs/<section>/<slug>.md.
2. Keep page references in docs/docs.json as absolute doc routes (for example, "/core/concepts").
3. Keep frontmatter keys minimal and compatible with current docs:
   • title (required)
   • description (required)
   • icon (optional)
4. Preserve existing Mintlify components and JSX blocks when present.
5. Use /docs/images/<file> for image paths in Markdown/HTML blocks.