Mintlify MDX Compiler & One-Way Sync

Compiles Sovereign Markdown Palace documents into Mintlify MDX trees and syncs to downstream docs repository under 5 strict safety guards.

This skill automates compiling standard Markdown documents in docs/ and skills in .agents/skills/ into Mintlify-compliant MDX (docs-source/) and executing a one-way synchronization pipeline to the downstream deployment repository (linuxmalaysia/my-knowledge-brain) serving https://harisfazillah.mintlify.site.

User Manual Site Style Standards

The compiler (tools/build_mintlify_mdx.py) and any manual MDX authoring must follow these formatting rules:

1. Frontmatter Requirements

Every generated .mdx file must contain valid YAML frontmatter:

---
title: "<50-60 char SEO title, unique across the site>"
sidebarTitle: "<1-3 word Title Case label>"
description: "<130-155 chars, unique, adds information beyond title>"
---

• sidebarTitle: Mandatory and short (1-3 words). Never put the full SEO title in the sidebar. Never repeat the product name.
• First Paragraph: Must be plain prose (no JSX components, no code fences) naming the feature and stating what the page covers.
• Punctuation: No em dashes (—) or en dashes (–) as punctuation in prose. Use commas, colons, parentheses, or split sentences.

2. Information Architecture (docs.json)

• navigation must be an object with tabs (≤ 2-3 tabs), ≤ 4-5 groups per tab, and ≥ 2 pages per group.
• Page paths must be extensionless with no leading slash (e.g. rituals/start-of-day).
• index.mdx is the landing page using <CardGroup> and <Steps> without raw HTML or inline CSS.

3. Mintlify Ignore Rules (docs-source/.mintignore)

Must explicitly ignore non-public assets:

AGENTS.md
AGENTS-PROMPT.md
drafts/
*.draft.mdx

The 5 Safety Guards (A-E)

Guard	Validation Target	Failure Consequence
Guard A	Source directory docs-source/ exists and docs.json is valid JSON.	Immediate abort before contacting remote repository.
Guard B	Count of .mdx files exceeds minimum floor (MIN_MDX_FILES, default 5).	Prevents empty or partial source from wiping downstream docs.
Guard C	Every navigation path in docs.json has a corresponding .mdx file.	Fails fast on broken links or missing page files.
Guard D	File deletions do not exceed cap (MAX_DELETIONS, default 10).	Blocks mass-deletion accidents unless ALLOW_LARGE_DELETIONS=true.
Guard E	Dry-run execution (--dry-run or DRY_RUN=true).	Previews planned additions/modifications/deletions without touching Git.

Step-by-Step Execution Workflow

Step 1: Compile Markdown to Mintlify MDX

When documents in docs/ or skills in .agents/skills/ are created or updated, run the compiler:

python tools/build_mintlify_mdx.py

Step 2: Validate with Local Dry-Run

Run the sync script in dry-run mode to verify all 5 guards and review the diff plan:

python scripts/sync_docs.py --dry-run

Step 3: Automated Push to Production

Push changes to main:

git add docs/ docs-source/ .agents/skills/
git commit -m "docs: update sovereign guides and regenerate mdx tree"
git push origin main

The GitHub Actions workflow .github/workflows/sync-docs.yml triggers automatically, executes the compiler, runs Guards A-E, and updates my-knowledge-brain using Docs Sync Bot <[e-mail]>.

Recovery Procedure

If the downstream repository is corrupted by an unintended push:

git clone https://github.com/linuxmalaysia/my-knowledge-brain.git
cd my-knowledge-brain
git log --oneline -n 5
git revert <bad-commit-sha>
git push origin main

Then resolve the discrepancy in deep-state-of-mind-for-my-ai under docs/ and re-run python scripts/sync_docs.py --dry-run.

---

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-23 Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0