Jira progress: loading…

ZAYAZ Documentation Automation

MDX & Category JSON Generation Guide

This guide explains how to prepare Excel metadata sheets and how to run the Python automation scripts that generate:

• MDX documentation files (with full frontmatter + body)
• Docusaurus category.json files for folders / sidebars

These scripts allow you to manage hundreds of documentation nodes in structured spreadsheets and regenerate files instantly.

⸻

1. 📘 MDX FILE GENERATION

The script:

/workspaces/zayaz-docs/tools/generate-mdx-from-xlsx.py

1.1 Required Excel structure

Your Excel file (tools/mdx-metadata.xlsx) must contain a sheet (Sheet1) with at least these two columns:

Column	Description
path	Path of the MDX file under /content/ (example: zayaz-platform/zayaz-platform.mdx)
content	The full MDX file contents, including frontmatter and body

Example rows

path.	content.
zayaz-platform/zayaz-platform.mdx	--- frontmatter here ---\n# Page Title\nBody text...
shared-intelligence/template-resolver.mdx	--- frontmatter here --- ...

IMPORTANT RULES

• path must not start with / → script strips automatically, but best to avoid.
• Frontmatter must begin with --- and end with ---.
• IDs must not contain slashes or colons (id: TR-PG, not TR/PG).
• **Titles must not contain colons (title: See - Page.., not See: Page..).
• YAML values containing : must be quoted: title: "APIs – Example endpoints"
• YAML lists must not contain empty entries.

The script automatically cleans these:

audience:
  -
  - internal-cto

becomes:

audience:
  - internal-cto

⸻

1.2 Running the MDX generator

From the repo root (/workspaces/zayaz-docs):

python3 tools/generate-mdx-from-xlsx.py tools/mdx-metadata.xlsx Sheet1

Where:

• tools/mdx-metadata.xlsx → your Excel file
• Sheet1 → sheet name (use the actual name Excel reports; visible via error printing)

What happens?

• All rows are processed
• Missing directories are automatically created
• Cleaned MDX files are written into /content/...
• The script prints each file as it is generated:

[mdx-gen] Wrote: content/zayaz-platform/zayaz-platform.mdx

⸻

2. 📁 CATEGORY JSON GENERATION

The script:

/workspaces/zayaz-docs/tools/generate-categories-from-xlsx.py

2.1 Required Excel structure

Your Excel sheet (tools/categories.xlsx, Sheet1) must include these columns:

Column	Description
folder	The relative folder path under /content/ (ex: zayaz-platform)
label	What Docusaurus shows in sidebar
position	Sidebar ordering number
collapsed	true or false
description	Optional description shown in sidebar UI

Example rows:

folder	label	position	collapsed	description
zayaz-platform	ZAYAZ Platform	1	FALSE	Main conceptual overview
shared-intelligence	Shared Intelligence Stack	2	TRUE	Core cross-system services

The script creates (or overwrites) /content/<folder>/_category_.json

Example output file:

{
  "label": "ZAYAZ Platform",
  "position": 1,
  "collapsed": false,
  "link": {
    "description": "Main conceptual overview"
  }
}

⸻

2.2 Running the category generator

From the repo root (/workspaces/zayaz-docs):

python3 tools/generate-categories-from-xlsx.py tools/categories.xlsx Sheet1

Output looks like:

[cat-gen] Wrote: content/zayaz-platform/_category_.json

⸻

3. 🛠️ Installation (first time only)

Inside Codespaces:

cd /workspaces/zayaz-docs
pip install openpyxl
chmod +x tools/generate-mdx-from-xlsx.py
chmod +x tools/generate-categories-from-xlsx.py

⸻

4. 🔍 Troubleshooting

YAML frontmatter errors

If Docusaurus prints:

Error while parsing Markdown front matter

Check for:

• Misaligned indentation
• A colon inside a title → use quotes
• Slashes inside id: → not allowed
• Empty YAML list items (script cleans this now)

Excel sheet not detected

If the script says:

Sheet 'mdx' not found

Excel may SHOW a sheet name but actually store it as Sheet1.

Just run:

python3 tools/generate-mdx-from-xlsx.py tools/mdx-metadata.xlsx Sheet1

Paths not created

The script automatically runs:

out_path.parent.mkdir(parents=True, exist_ok=True)

So nested folder structures are supported.

⸻

5. ✔️ Summary Cheat Sheet

Generate MDX files

python3 tools/generate-mdx-from-xlsx.py tools/mdx-metadata.xlsx Sheet1

Generate category.json folders

python3 tools/generate-categories-from-xlsx.py tools/categories.xlsx Sheet1

⸻