Skip to main content

Content-First Study Page Repair Design

Goal​

Repair the previous site-wide enrichment so the docs are easier to understand, less repetitive, more directly useful for students, and better suited for readers who want intuitive explanations, examples, and review prompts.

Problem​

The current enrichment added structure to many pages, but the added blocks are too generic. Repeated learning objectives, generic concept maps, and broad practice questions create noise instead of insight. Students need pages that answer: what is this topic, why does it matter, how do the parts connect, what example makes it concrete, what mistakes should I avoid, and what should I think about next?

Approach​

Use a content-first repair script that removes the earlier generic enrichment and inserts a smaller page-specific study block generated from the page's own title, headings, paragraphs, code fences, tables, and subject area. The block should be useful even when the original page is thin, but it should not pretend to replace a real domain rewrite.

Page Quality Rules​

  • Remove repetitive generic sections such as Learning Objectives, Why This Matters, and generic revision tables.
  • Preserve original author content, headings, code examples, tables, links, and front matter.
  • Add concise, page-aware sections only after the real title or at the top of content.
  • Prefer direct explanations, concrete examples, and question prompts over high-level filler.
  • Use Mermaid diagrams only when they are based on actual page headings or child pages.
  • Keep high-stakes legal, medical, and pharmacy pages careful: improve clarity and examples from existing material, but do not invent current legal or clinical facts.
  • Flag thin pages and pages that need source-backed expansion in generated reports.

Student-Facing Blocks​

Regular pages receive:

  • ## Study Snapshot: a short SEO-friendly summary of what the page actually covers.
  • ## How to Understand This Topic: three direct reading cues based on headings and content.
  • ## Concept Flow: a Mermaid diagram built from the page's actual sections.
  • ## Key Terms and Ideas: terms found in headings and bold text, with short study prompts.
  • ## Relatable Example: a mock scenario, case, dry run, or application tied to the subject and title.
  • ## Check Your Understanding: thought-provoking questions based on the page sections.
  • ## What to Review Next: targeted follow-up suggestions and, when needed, a note that deeper source-backed expansion is required.

Index pages receive:

  • ## How to Use This Section: a short guide based on actual child page titles.
  • ## Suggested Learning Path: a Mermaid path using child pages.
  • ## Build Understanding: prompts that help students connect the child pages.

Missing Pages​

The repair should add useful subject-level bridge documents only where they improve learning across a whole subject. These include concise pages such as Core Concepts and Study Strategy and Worked Examples and Case Studies, linked through subject index pages by Docusaurus sidebar discovery.

Verification​

  • Run the repair script in dry-run and normal modes.
  • Confirm generic sections are removed.
  • Confirm new content blocks exist across docs.
  • Confirm Markdown code fences are balanced.
  • Run npm run build.
  • Record existing warnings separately from new failures.
Last updated on