WP Performance Notion Migration Log

This document records the full migration of the WP Performance curriculum from Notion export into Docusaurus, including the exact issues found, solutions applied, commands used, and reusable guidance for future AI migration tasks.

1. Objective

• Migrate Notion-exported WP Performance pages into a clean Docusaurus structure.
• Replace existing placeholder tree at docs/wordpress/wp-performance-optimization with source-aligned content.
• Preserve curriculum mapping and sidebar order.
• Keep empty source pages visible as placeholders (per user decision).
• Ensure build-safe Markdown/MDX output.

2. Source and Destination

Item	Path
Notion source folder	/home/rezriz/notion-export -to-docusaurus/wp-performance
Source zip used	/home/rezriz/notion-export -to-docusaurus/wp-performance/ExportBlock-57d9ade8-2c48-496e-b5c3-f473e54c6b54-Part-1.zip
Curriculum root page inside zip	WP Performance Optimization 26f05f1abc3d803aae50f752b7d4a81e.md
Docusaurus target root	/opt/docker-data/apps/docusaurus/site/docs/wordpress/wp-performance-optimization
Sidebar config	/opt/docker-data/apps/docusaurus/site/sidebars.js
Navbar config	/opt/docker-data/apps/docusaurus/site/docusaurus.config.js

3. Search and Discovery Protocol

Per user requirement, discovery used Linux search tools with sudo for outside-repo exploration.

Commands used for discovery

sudo fdfind -e md . "/home/rezriz/notion-export -to-docusaurus/wp-performance"
sudo fdfind . "/opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/11. Migration"
sudo fdfind -e py . "/home/rezriz/github/scripts"
sudo rg -n "notion|docusaurus|frontmatter|_category_|sidebar_position|fix_mdx|reorganize|clean" "/home/rezriz/github/scripts"
sudo plocate --regex '/home/rezriz/.*\.py$' | rg -i "notion|docusaurus|migration|wp-cli|mdx|frontmatter"

4. Migration Strategy Executed

4.1 Curriculum-first mapping

• Parsed the Notion curriculum root page.
• Used that page as the single source of truth for module order and lesson order.
• Mapped module numbers to stable Docusaurus folder slugs (example: 10. Cache Strategy -> cache-strategy).

4.2 Rebuild target tree

• Cleared existing contents under docs/wordpress/wp-performance-optimization.
• Recreated:
  • root index.md
  • 17 module folders
  • per-module _category_.json
  • per-module index.md
  • lesson docs with frontmatter and ordering

4.3 Content cleanup rules

• Removed Notion artifacts:
  • <aside> wrappers
  • Notion home icon and home nav block
  • repeated curriculum navigation block
  • trailing export wrappers
• Normalized headings and spacing.
• Converted output to ASCII-safe text for consistency.
• Applied MDX safety cleanup for problematic < text (outside code fences).

4.4 Placeholder policy for empty source pages

• 19 source pages had no real body content after Notion artifact removal.
• Created placeholder docs with explicit note and original source filename.
• Kept these pages in sidebar to preserve curriculum completeness.

5. Final Output Metrics

Metric	Value
Module folders	17
Lesson docs	131
Placeholder lessons	19
Module indexes	17
Root index	1
_category_.json files	17
Total .md files under target	149

Placeholder distribution

Module Folder	Lessons	Placeholders
backend-optimization	7	2
cache-strategy	7	1
cdn-delivery	7	2
core-web-vitals	14	0
database-tuning	9	1
design-factor	6	0
foundation	4	0
image-optimization	6	0
monitoring	7	7
php-optimization	5	0
pricing-strategy	3	0
resource-prioritization	8	0
security-stability	6	6
server-optimization	9	0
web-server-optimization	8	0
workflow	19	0
wp-core-setup	6	0

6. Issues Found and Solutions Applied

Issue	Symptom	Root Cause	Solution
Link parser dropped lessons	Initial migration produced 123 lessons instead of 131	Regex failed on titles/URLs containing [] and ()	Replaced with robust parser based on first ]( and trailing )
Empty source pages	Some modules appeared blank after cleanup	Notion pages were placeholders with only nav wrappers	Generated explicit placeholder lessons and retained sidebar entries
MDX build failures	Unexpected character before name in many files	Raw < comparisons outside code blocks parsed as JSX	Escaped < to &lt; outside fenced code blocks
Notion export noise	Duplicate nav and wrappers in content	Notion embeds global navigation and <aside> markup	Removed <aside>, icon lines, home nav, and wrapper separators
Container/permission friction	Build and git operations blocked in non-sudo context	Docker and repo ownership restrictions	Used sudo for container execution and repo status checks

7. Scripts Used and Referenced

7.1 One-off scripts executed in this migration

• Multiple inline Python scripts were executed via python3 - <<'PY' to:
  • parse curriculum mapping from root Notion page
  • rebuild folder and file structure
  • clean content and generate frontmatter
  • compute placeholder statistics
  • apply global MDX safety fix for < outside code fences

7.2 Existing reference scripts (read and adapted conceptually)

Script	Path	Purpose used as reference
reorganize_wpcli_structure.py	/home/rezriz/github/scripts/reorganize_wpcli_structure.py	Category/folder organization pattern
add_wpcli_frontmatter.py	/home/rezriz/github/scripts/add_wpcli_frontmatter.py	Frontmatter consistency pattern
clean_notion_formatting.py	/home/rezriz/github/scripts/clean_notion_formatting.py	Notion artifact cleanup ideas
fix_mdx_universal.py	/home/rezriz/github/scripts/fix_mdx_universal.py	MDX angle bracket safety approach
wp_cli_docs_cleanup.py	/home/rezriz/github/scripts/wp_cli_docs_cleanup.py	General markdown cleanup logic

8. Sidebar and Navbar Integration Changes

• Added WP Performance sidebar in sidebars.js:
  • wpWpPerformanceOptimizationSidebar: [{ type: 'autogenerated', dirName: 'wordpress/wp-performance-optimization' }]
• Added WP navbar item in docusaurus.config.js under WP dropdown:
  • docId: 'wordpress/wp-performance-optimization/index'
  • sidebarId: 'wpWpPerformanceOptimizationSidebar'
  • label: WP Performance
• Updated docs/wordpress/index.md to include links to core WordPress sections including WP Performance Optimization.

9. Validation and Build

9.1 Content-level checks

rg -n "<aside>|</aside>|notion\.so/icons/home_|Curriculum outline|Home of self-learn curriculum" \
  "/opt/docker-data/apps/docusaurus/site/docs/wordpress/wp-performance-optimization"

Result: no residual Notion nav artifacts in migrated target.

9.2 Build verification

sudo docker exec docusaurus sh -lc "cd /app && npx docusaurus build --no-minify"

Result: build completed successfully after MDX fixes.

Notes:

• Some unrelated pre-existing warnings remain outside this migration scope (blog author warning, deprecated config warning, one old markdown directive warning in server docs).

10. Re-run Procedure for Future AI Agents

1. Discover source with sudo fdfind and verify zip contents.
2. Parse curriculum root page first; do not rely on filename-only ordering.
3. Build deterministic module-to-folder map.
4. Regenerate entire target subtree to avoid stale legacy files.
5. Keep empty-source policy explicit (placeholder vs skip) based on user decision.
6. Run MDX safety pass for < outside code blocks.
7. Run container build and fix errors before handoff.
8. Document counts, placeholder list, and changed config files.

11. Important Implementation Notes

• Notion link lines can contain nested brackets in titles (example: [Open Lite Speed [3.0]](...)) and parentheses in URLs. Avoid simplistic link regex.
• A migration that appears visually fine can still fail MDX parse; always run build.
• Preserve curriculum order from source root map, not from alphabetical filename order.
• Keep migration logs in this folder for reproducibility and AI continuity.