Skip to main content

Site-Wide Student Enrichment Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Enrich all docs/ study pages with student-focused learning structure, diagrams, examples, revision aids, and practice prompts.

Architecture: Use a repeatable Node.js enrichment script to update Markdown files in subject-aware batches. Enable Docusaurus Mermaid support first so generated diagrams are rendered and validated by the production build.

Tech Stack: Docusaurus 3, Markdown/MDX, Mermaid, Node.js scripts, shell verification with rg, awk, and npm run build.

Task 1: Enable Mermaid Rendering​

Files:

  • Modify: package.json

  • Modify: package-lock.json

  • Modify: docusaurus.config.js

  • Step 1: Install Mermaid theme

Run:

npm install @docusaurus/theme-mermaid@3.5.2

Expected: package.json and package-lock.json include @docusaurus/theme-mermaid.

  • Step 2: Configure Docusaurus

Modify docusaurus.config.js so the top-level config includes:

  markdown: {
    mermaid: true,
  },

  themes: ['@docusaurus/theme-mermaid'],

Place these near the existing top-level plugins/presets fields, not inside themeConfig.

  • Step 3: Build check

Run:

npm run build

Expected: build exits 0; existing unrelated warnings may remain.

Task 2: Create Enrichment Script​

Files:

  • Create: scripts/enrich_student_notes.mjs

  • Step 1: Create a Node.js script

Create scripts/enrich_student_notes.mjs with these responsibilities:

  • Walk docs/ recursively for .md and .mdx files.

  • Skip docs/superpowers/.

  • Preserve front matter.

  • Detect index.md pages and use the index-page pattern.

  • Detect subject from the first folder under docs/.

  • Skip a section if the page already has that section heading.

  • Insert an enrichment block after the first H1 for regular study pages.

  • Insert a lighter learning-path block after the first H1 for index pages.

  • Generate conservative Mermaid diagrams using only simple node labels and arrows.

  • Avoid raw LaTeX syntax and JSX-like braces.

  • Step 2: Implement subject helpers

The script must include subject profiles for:

Software_engineer_interview_prep
Computer_Science
Electronics
Bio_Technology
Medicine
Pharmacy
Law
Economics
Business_Administration
Commercial_Applications
Hotel_Management
Psychology
default

Each profile should provide:

  • Learning-objective verbs.

  • Diagram node labels.

  • Worked-example label.

  • Common mistake wording.

  • Practice question style.

  • Step 3: Add dry-run support

The script must support:

node scripts/enrich_student_notes.mjs --dry-run
node scripts/enrich_student_notes.mjs

Expected dry-run output: counts of candidate files by subject and number of files that would be changed.

Task 3: Apply Enrichment​

Files:

  • Modify: all eligible Markdown/MDX files under docs/

  • Step 1: Dry run

Run:

node scripts/enrich_student_notes.mjs --dry-run

Expected: output lists all subject groups and a nonzero change count.

  • Step 2: Apply script

Run:

node scripts/enrich_student_notes.mjs

Expected: pages are updated in place and output reports changed file count.

  • Step 3: Spot-check representative pages

Inspect:

sed -n '1,180p' docs/Software_engineer_interview_prep/100-SameTree.md
sed -n '1,180p' docs/Electronics/15._VLSI_Design/2._CMOS_Technology.md
sed -n '1,180p' docs/Law/Criminal_Law/2._Classification_of_Offenses.md
sed -n '1,180p' docs/Medicine/1._Anatomy/1._Introduction_to_Anatomy.md

Expected: each page has useful learning sections, a build-safe diagram, and no duplicated section headings.

Task 4: Verification​

Files:

  • Read: all Markdown/MDX files

  • Step 1: Placeholder scan

Run:

rg -n -i '\bTBD\b|placeholder\.com|via\.placeholder|content provided is a draft|^\s*\.\.\.\s*$|^\s*[0-9]+\.\s*(TBD\.\.\.|\.\.\.)\s*$|^\s*Let.s begin.*\.\.\.|^\s*Let.s dive deeper.*\.\.\.' docs blog src/pages privacypolicy -g '!docs/superpowers/**'

Expected: no true incomplete-page hits.

  • Step 2: Code-fence scan

Run:

find docs blog privacypolicy src/pages -type f \( -name '*.md' -o -name '*.mdx' \) -print0 | xargs -0 awk 'FNR==1{if (file && count%2==1) print file; file=FILENAME; count=0} /^```/{count++} END{if (file && count%2==1) print file}'

Expected: no output.

  • Step 3: Mermaid fence count

Run:

rg -n '^```mermaid' docs | wc -l

Expected: a nonzero count.

  • Step 4: Build

Run:

npm run build

Expected: build exits 0; existing unrelated warnings may remain.

Task 5: Commit and Cleanup​

Files:

  • Commit all modified files

  • Step 1: Review status

Run:

git status --short
git diff --stat

Expected: changes are limited to docs enrichment, Mermaid configuration, package files, and the enrichment script.

  • Step 2: Commit

Run:

git add docusaurus.config.js package.json package-lock.json scripts/enrich_student_notes.mjs docs
git commit -m "docs: enrich study pages for students"

Expected: commit succeeds.

Last updated on