Skip to main content

Investigate: Improve 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 in Docusaurus to show the full README content, template logo, install command, and better navigation — making each page a complete reference for the template.

Priority: High

Last Updated: 2026-03-31

Related:

Context​

The template detail pages (e.g., https://tmp.sovereignsky.no/docs/templates/web-server/csharp-basic-webserver/) are generated by scripts/generate-docs-markdown.sh. Currently they show metadata in a table, a summary, tags as backtick text, and related templates as plain text. The pages are functional but dry — they don't show the README content, the logo, or how to install the template.

Current State​

The generated page looks like:

# C# Basic Webserver

ASP.NET Core server with health endpoint and Docker support

| | |
|---|---|
| **Category** | Web Server Templates |
| **Version** | 1.0.0 |
| **Tools** | dev-csharp |
| **Website** | [link](link) |
| **Docs** | [link](link) |

## Summary
(TEMPLATE_SUMMARY)

## Tags
`csharp` `dotnet` `aspnet` ...

## Related Templates
- java-basic-webserver
- golang-basic-webserver

Problems​

  1. No README content — the most useful information (Quick Start, Project Structure, how to run) is in the template's README file but not shown on the page
  2. No logo — each template has an SVG logo but it's not displayed
  3. No install command — user doesn't know how to install the template (dev-template csharp-basic-webserver)
  4. Related templates not linked — plain text instead of clickable links
  5. Metadata table is dry — framework links buried in a table, not prominent
  6. Tags not styled — backtick text instead of visual badges
  7. No visual hierarchy — everything looks the same weight

Proposed Page Layout​

[Logo 64x64]  C# Basic Webserver  v1.0.0
              ASP.NET Core server with health endpoint and Docker support

              Install:  dev-template csharp-basic-webserver

              [Website ↗]  [Docs ↗]

              csharp  dotnet  aspnet  webserver  api  rest

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Quick Start
(from README-csharp-basic-webserver.md)

## Prerequisites
(from README)

## Project Structure
(from README)

## Development
(from README)

## Docker Build
(from README)

## Kubernetes Deployment
(from README)

## CI/CD
(from README)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Related Templates
- [Java Basic Webserver](../web-server/java-basic-webserver)
- [Go Basic Webserver](../web-server/golang-basic-webserver)

Implementation Approach​

How to embed README content​

The generate-docs-markdown.sh script already reads TEMPLATE_INFO for each template. It needs to also:

  1. Read TEMPLATE_README to get the README filename (e.g., README-csharp-basic-webserver.md)
  2. Find the README file in the template directory (e.g., templates/csharp-basic-webserver/README-csharp-basic-webserver.md)
  3. Strip the # Title heading from the README (the page already has a title)
  4. Embed the README content into the generated page below the metadata header

For app templates, the README lives in templates/<name>/. For ai-templates, it lives in ai-templates/<name>/template/.

In the generated markdown, use an image reference:

![C# Basic Webserver logo](/img/templates/csharp-basic-webserver-logo.svg)

Or for better layout control, the page could use a Docusaurus MDX component. However, keeping it as pure markdown makes the generation script simpler.

How to show the install command​

Generate a code block with the install command:

**Install:**
\`\`\`bash
dev-template csharp-basic-webserver
\`\`\`

The template directory name (used by dev-template.sh) matches the TEMPLATE_ID.

Currently the script outputs plain text. It needs to resolve each related ID to the correct category directory:

- [Java Basic Webserver](../web-server/java-basic-webserver)

This requires looking up each related template's category to build the correct path.

Changes Needed​

scripts/generate-docs-markdown.sh​

  1. Read and embed README content (strip first heading line)
  2. Add logo image at the top
  3. Add install command code block
  4. Resolve related template links to correct paths
  5. Style tags as space-separated backtick badges (already done, but could be improved)

Category index pages​

  1. Show logo next to each template name in the table
  2. Add install command column or note

Templates overview page​

  1. Consider showing logos in the overview table

Questions to Answer​

  1. Should the README content be embedded as-is, or should certain sections be excluded/reorganised? — As-is. We don't know what advanced templates will look like in the future, so don't assume a fixed structure.
  2. Should the install command differentiate between app templates and AI templates? — Yes. App templates: dev-template <id>. AI templates: dev-template-ai <id>.
  3. Should the header section be pure markdown or use an MDX component for better styling? — Make it look nice. Use whatever approach gives the best result.
  4. Should category index pages also show logos? — Yes.
  5. Should the TemplateCard React component on /templates also be updated to match the new style? — Yes.

Inspiration: UIS Services Pages​

The UIS site (https://uis.sovereignsky.no/services) provides a good reference for how template pages should look.

UIS Services Overview Page​

  • Categories displayed as clickable cards with icon, title, description, service count
  • Pre-configured stacks section with grouped service logos
  • "All Services" grid with cards showing: logo, linked name, one-line description, tags
  • Responsive grid layout
  • Clicking a card navigates to the detail page

UIS Service Detail Page (e.g., Grafana)​

  • Breadcrumb navigation: Services > Observability > Grafana
  • Title + subtitle (description)
  • Metadata panel with deploy/undeploy commands, dependencies, helm chart, namespace
  • Content sections: What It Does, Deploy, Verify, Configuration, Undeploy, Troubleshooting, Learn More
  • Code blocks for commands
  • Tables for reference data
  • Right-side navigation with section anchors

What to adapt for templates​

The UIS detail page pattern maps well to templates:

UIS ServiceTemplate Equivalent
Deploy command: ./uis deploy grafanaInstall command: dev-template csharp-basic-webserver
DependenciesTools: dev-csharp
Helm chart, NamespaceWebsite, Docs links
What It DoesAbout (TEMPLATE_SUMMARY)
Deploy, Verify, Configuration...README content (Quick Start, Prerequisites, Project Structure...)

The key difference: UIS has structured sections written per-service. Templates embed the full README as-is — this is simpler to maintain and works for any template structure.

UIS React Component Architecture (studied for reuse)​

UIS has a well-structured component system we should adapt:

Components to adapt​

UIS ComponentTemplate EquivalentWhat it does
ServiceCardTemplateCard (update existing)Logo 64x64, title link, abstract (2-line clamp), up to 3 tags. Hover: shadow + translate.
ServiceGridTemplateGrid (update existing)Groups by category with category logo + name + count header. Responsive: 1→2→3→4 columns.
CategoryCardCategoryCard (new)Logo 48x48, title, description, template count. Links to category section.
CategoryGridCategoryGrid (new)Grid of CategoryCards. Excludes empty categories.

Styling approach​

UIS uses CSS Modules (not inline styles). Our current TemplateCard/TemplateGrid use inline styles. We should switch to CSS Modules to match UIS and get:

  • Dark mode support via [data-theme='dark'] selectors
  • Responsive grid via @media queries
  • Hover effects with box-shadow and transform
  • Text truncation with -webkit-line-clamp
  • Docusaurus design tokens (--ifm-* CSS variables)

Data utilities​

UIS has a utils/data.ts with functions like getServices(), getServicesByCategory(), getServiceCountByCategory(). We should create utils/data.ts with equivalent template functions.

UIS also has utils/paths.ts for generating category folders and service detail paths. We need the same.

Type definitions​

UIS has TypeScript types in types/service.ts and types/category.ts. We should create types/template.ts and types/category.ts.

Page structure (adapted from UIS /services)​

/templates page:
1. Header: "Templates" + subtitle
2. CategoryGrid: clickable category cards with template count
3. All Templates: TemplateGrid grouped by category
   - Each category section: logo + name + count + grid of TemplateCards
   - Cards link to /docs/templates/<category>/<template-id>

Detail pages (generated MDX)​

Use an MDX component TemplateHeader for the header section:

import TemplateHeader from '@site/src/components/TemplateHeader';

<TemplateHeader
  logo="/img/templates/csharp-basic-webserver-logo.svg"
  name="C# Basic Webserver"
  version="1.0.0"
  description="ASP.NET Core server with health endpoint and Docker support"
  install="dev-template csharp-basic-webserver"
  website="https://dotnet.microsoft.com/apps/aspnet"
  docs="https://learn.microsoft.com/aspnet/core/"
  tags={["csharp", "dotnet", "aspnet", "webserver", "api", "rest"]}
/>

## Summary
(TEMPLATE_SUMMARY)

---

(README content embedded here)

---

## Related Templates
- [linked templates]

This gives a styled header with logo, install command, links, and tags — then the README content below in standard markdown.

Gaps Identified — All Resolved​

1. MDX with TemplateHeader component — Resolved​

Use MDX. The generation script outputs .mdx files that import a TemplateHeader React component for the styled header (logo + name + version + install command + links + tags). The README content below remains standard markdown. This gives full styling control for the header while keeping README embedding simple.

2. Two template pages — Resolved​

Keep both, following the UIS pattern:

  • /templates (React page) = "marketing" overview with visual cards grouped by category. Like UIS /services.
  • /docs/templates/ (generated markdown) = detailed documentation with full README content, install commands, metadata. Like UIS /docs/services/.

Cards on /templates link to the detail pages in /docs/templates/. Both serve different purposes and both need updating.

3. README path differs for ai-templates — Resolved​

The script must handle both paths:

  • App templates: templates/<name>/<TEMPLATE_README>
  • AI templates: ai-templates/<name>/template/<TEMPLATE_README>

4. TEMPLATE_SUMMARY kept alongside README — Resolved​

Keep the Summary section from TEMPLATE_SUMMARY as a short intro before the embedded README content. We don't know what people will write in future README files — the summary provides a consistent description.

5. README file must always exist — Resolved​

Add a check to scripts/validate-metadata.sh (or validate-docs.sh) that verifies the README file referenced by TEMPLATE_README actually exists. If missing, it's a validation error that blocks the build.

6. Right-side TOC — Try and decide​

Docusaurus auto-generates a table of contents from headings. The embedded README headings will appear there. We try it and decide if it looks good — if not, we can suppress it.

7. TemplateCard/TemplateGrid styling — Resolved​

Switch from inline styles to CSS Modules to match UIS pattern. Add dark mode support, responsive grid, hover effects, text truncation. Add CategoryCard and CategoryGrid components.

8. Validate README exists — Resolved​

Add to scripts/validate-metadata.sh: check that the file referenced by TEMPLATE_README exists at the expected path. App templates: templates/<name>/<TEMPLATE_README>. AI templates: ai-templates/<name>/template/<TEMPLATE_README>.

9. Auto-commit pattern — Resolved​

Keep auto-commit in CI, same as UIS. Generated files are committed to git. First run after this change will produce a larger auto-commit as all pages are regenerated.

10. Two description sections — Resolved​

Keep both. Summary (TEMPLATE_SUMMARY) is a consistent short intro above a horizontal rule. README content is the full documentation below. The horizontal rule visually separates them.

Changes Needed (updated)​

scripts/generate-docs-markdown.sh​

  1. Output .mdx files instead of .md for template detail pages
  2. Import and render TemplateHeader component with metadata props
  3. Read and embed README content (strip first heading line)
  4. Add install command (differentiate dev-template vs dev-template-ai based on template type)
  5. Resolve related template links to correct paths with template names

scripts/validate-metadata.sh​

  1. Add check: verify README file referenced by TEMPLATE_README exists

New React components​

  1. Create TemplateHeader MDX component for detail pages
  2. Update TemplateCard — switch to CSS Module, match UIS ServiceCard style
  3. Update TemplateGrid — switch to CSS Module, match UIS ServiceGrid style
  4. Create CategoryCard — adapted from UIS CategoryCard
  5. Create CategoryGrid — adapted from UIS CategoryGrid

New utility/type files​

  1. Create types/template.ts and types/category.ts
  2. Create utils/data.ts (getTemplates, getTemplatesByCategory, etc.)
  3. Create utils/paths.ts (getCategoryFolder, getTemplatePath, etc.)

CSS Modules​

  1. Create CSS modules for all components (dark mode, responsive, hover effects)

Update existing​

  1. Update /templates page to use CategoryGrid + TemplateGrid
  2. Update category index pages to show logos

Next Steps​

  • Create PLAN for the page redesign ✓ — see plans/completed/PLAN-docusaurus-template-pages.md