Skip to main content

Plan: Redesign Docusaurus Template Pages

IMPLEMENTATION RULES: Before implementing this plan, read and follow:

Status: Completed​

Completed: 2026-03-31

Goal: Redesign the generated template detail pages and the /templates overview page to show full README content, logos, install commands, and better navigation — following UIS component patterns with CSS Modules and MDX.

Investigation: INVESTIGATE-docusaurus-template-pages.md

Last Updated: 2026-03-31

Overview​

This plan has 8 phases:

  1. TypeScript types and data utilities (foundation)
  2. TemplateHeader MDX component for detail pages
  3. Update generate-docs-markdown.sh to output MDX with README content
  4. TemplateCard and TemplateGrid with CSS Modules
  5. CategoryCard, CategoryGrid, and /templates page redesign
  6. Add README existence validation
  7. Docusaurus category structure (follow UIS pattern)
  8. Category rename and cleanup

Phase 1: TypeScript Types and Data Utilities — DONE​

  • 1.1 Create website/src/types/template.ts ✓
  • 1.2 Create website/src/types/category.ts ✓
  • 1.3 Create website/src/utils/data.ts (getTemplates, getCategories, getTemplatesByCategory, etc.) ✓
  • 1.4 Create website/src/utils/paths.ts (getCategoryFolder, getTemplatePath, getCategoryAnchor) ✓

Phase 2: TemplateHeader MDX Component — DONE​

  • 2.1 Create website/src/components/TemplateHeader/index.tsx ✓
  • 2.2 Create website/src/components/TemplateHeader/styles.module.css (flexbox, dark mode, responsive, monospace install) ✓

Phase 3: Update generate-docs-markdown.sh for MDX + README Embedding — DONE​

  • 3.1 Update script to output .mdx files with TemplateHeader import, README embedding, install command differentiation (dev-template vs dev-template-ai), related template link resolution ✓
  • 3.2 Category index pages: table with Template, Description, Install columns (no logos — matches UIS style) ✓
  • 3.3 Script generates _category_.json files for Docusaurus sidebar ✓
  • 3.4 Renamed "About" section to "Summary" (shows TEMPLATE_SUMMARY) ✓
  • 3.5 Removed custom templates/index.md — Docusaurus auto-generates category landing page ✓

Phase 4: TemplateCard and TemplateGrid with CSS Modules — DONE​

  • 4.1 Create website/src/components/TemplateCard/styles.module.css (hover shadow, 2-line clamp, tag badges) ✓
  • 4.2 Create website/src/components/TemplateCard/index.tsx (CSS Module, useBaseUrl, getTemplatePath, max 3 tags) ✓
  • 4.3 Create website/src/components/TemplateGrid/styles.module.css (responsive 1→2→3 columns) ✓
  • 4.4 Create website/src/components/TemplateGrid/index.tsx (category headers with logo + name + count, anchor IDs) ✓

Phase 5: CategoryCard, CategoryGrid, and /templates Page Redesign — DONE​

  • 5.1 Create website/src/components/CategoryCard/index.tsx (logo 48x48, title, description, count, links to anchor) ✓
  • 5.2 Create website/src/components/CategoryCard/styles.module.css (hover border color change) ✓
  • 5.3 Create website/src/components/CategoryGrid/index.tsx (excludes empty categories) ✓
  • 5.4 Create website/src/components/CategoryGrid/styles.module.css (responsive 1→2→3 columns) ✓
  • 5.5 Rewrite website/src/pages/templates.tsx (Categories section + All Templates section) ✓
  • 5.6 Delete old standalone TemplateCard.tsx and TemplateGrid.tsx ✓

Phase 6: Add README Existence Validation — DONE​

  • 6.1 Update scripts/validate-metadata.sh to check README file exists at correct path (app vs ai template) ✓

Phase 7: Docusaurus Category Structure — DONE​

Following UIS pattern: /docs/category/templates as auto-generated category landing, /docs/templates/<category>/ as category index with table.

  • 7.1 Create _category_.json files for templates root and each category ✓
  • 7.2 Generation script auto-creates _category_.json for each category ✓
  • 7.3 Update docs/index.md link to category/templates ✓

Phase 8: Category Rename — DONE​

Renamed WEB_SERVER to BASIC_WEB_SERVER to clarify these are basic Hello World templates.

  • 8.1 Update scripts/lib/categories.sh: WEB_SERVER → BASIC_WEB_SERVER, new display name and description ✓
  • 8.2 Update all 6 web server TEMPLATE_INFO files: TEMPLATE_CATEGORY="BASIC_WEB_SERVER" ✓
  • 8.3 Remove old website/docs/templates/web-server/ folder ✓
  • 8.4 Regenerate all pages ✓

Acceptance Criteria​

  • Detail pages use MDX with TemplateHeader component (logo, install command, links, tags) ✓
  • Detail pages embed full README content below the header ✓
  • Detail pages show "Summary" section from TEMPLATE_SUMMARY ✓
  • Install command shows dev-template for app, dev-template-ai for ai templates ✓
  • Related templates are clickable links with correct paths ✓
  • /templates page has CategoryGrid + TemplateGrid matching UIS pattern ✓
  • All components use CSS Modules with dark mode support ✓
  • Category index pages use clean table (Template, Description, Install) ✓
  • Docusaurus auto-generates category landing page (like UIS) ✓
  • validate-metadata.sh checks README file exists ✓
  • Category renamed from WEB_SERVER to BASIC_WEB_SERVER ✓
  • Full pipeline (validate → generate → build) succeeds locally ✓