docs: replace prepare-docs.sh with rehype plugin and frontmatter (#435)

* docs: replace prepare-docs.sh with rehype plugin and frontmatter

Eliminate the .docs-temp preprocessing pipeline by:

- Adding a rehype plugin (rehype-rewrite-links.mjs) that rewrites .md
  links at build time, replacing the fragile sed-based approach
- Adding minimal frontmatter (title + description) to all 31 doc files
  and removing H1 headings (Starlight renders title as H1)
- Pointing the content loader directly at ../docs/ with glob exclusions
- Adding a global Banner component override for the feedback banner
- Removing prepare-docs.sh and all references to .docs-temp

Closes #423

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: preserve frontmatter in generate-cli-docs.sh

The CLI docs generation script overwrites cli.md from scratch. Update it
to prepend the required YAML frontmatter (title + description) before
the auto-generated content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: strip H1 from generated CLI docs to match frontmatter title

The --markdown-help output includes a `# Command-Line Help` H1 heading.
Since we now use frontmatter title (which Starlight renders as H1),
strip the generated H1 to avoid duplication and match the committed file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: marc0olo

.claude/docs-guidelines.md

@@ -42,7 +42,7 @@ Documentation follows the Diátaxis framework:
 Source documentation in `docs/` must work in two contexts:
 
 1. **GitHub**: Renders Markdown directly with `.md` extensions
-2. **Starlight docs site**: `scripts/prepare-docs.sh` transforms links to clean URLs
+2. **Starlight docs site**: A rehype plugin (`docs-site/plugins/rehype-rewrite-links.mjs`) transforms links to clean URLs at build time
 
 **Link format rules:**
 
@@ -62,4 +62,4 @@ Source documentation in `docs/` must work in two contexts:
 [root-level link](../tutorial.md)
 ```
 
-The `prepare-docs.sh` script handles the transformation to Starlight's URL structure. If you add new link patterns, verify they work by building the docs site locally with `cd docs-site && npm run build`.
+The rehype plugin handles the transformation to Starlight's URL structure at build time. If you add new link patterns, verify they work by building the docs site locally with `cd docs-site && npm run build`.

.github/CONTRIBUTING.md

@@ -94,15 +94,12 @@ Documentation follows the [Diátaxis framework](https://diataxis.fr/):
 
 The documentation site uses [Astro](https://astro.build/) with [Starlight](https://starlight.astro.build/):
 
-1. **Source files** (`docs/`) are plain Markdown without frontmatter
-2. **Build script** (`scripts/prepare-docs.sh`) runs before each build and:
-   - Copies docs to `.docs-temp/` directory (excluding schemas and READMEs)
-   - Adjusts relative paths and strips `.md` extensions for Starlight's clean URLs
-   - Extracts titles from H1 headings and adds frontmatter
-3. **Starlight** reads from `.docs-temp/` and builds the site
+1. **Source files** (`docs/`) are Markdown with minimal YAML frontmatter (title + description)
+2. **Starlight** reads directly from `docs/` via the glob content loader
+3. **Rehype plugin** (`docs-site/plugins/rehype-rewrite-links.mjs`) rewrites `.md` links at build time for Starlight's clean URLs
 4. **GitHub Actions** automatically deploys to GitHub Pages on push to main
 
-This architecture keeps source docs clean and GitHub-friendly while providing a polished documentation site.
+This architecture keeps source docs GitHub-friendly (`.md` links work on GitHub) while producing clean URLs on the documentation site.
 
 ### Versioned Documentation Deployment
 
@@ -194,7 +191,7 @@ When submitting a documentation PR:
 - Check that all links work (both in GitHub and on the site)
 - Follow the Diátaxis framework for placing content in the right section
 - Verify your examples work by testing them
-- Run `./scripts/prepare-docs.sh` locally to check for build errors
+- Run `npm run build` in `docs-site/` locally to check for build errors
 
 For more details on the documentation system, see:
 - [docs/README.md](../docs/README.md) - Documentation writing guide

.github/workflows/docs.yml

@@ -10,13 +10,11 @@ on:
     paths:
       - 'docs/**'
       - 'docs-site/**'
-      - 'scripts/prepare-docs.sh'
       - '.github/workflows/docs.yml'
   pull_request:
     paths:
       - 'docs/**'
       - 'docs-site/**'
-      - 'scripts/prepare-docs.sh'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 

.gitignore

@@ -19,4 +19,3 @@ docs-site/.astro/
 docs-site/dist/
 docs-site/dist-test/
 docs-site/node_modules/
-docs-site/.docs-temp/

README.md

@@ -107,9 +107,6 @@ cargo fmt && cargo clippy
 # Preview documentation site locally
 cd docs-site && npm install && npm run dev
 # Opens at http://localhost:4321
-
-# Prepare docs for build (runs automatically during build)
-./scripts/prepare-docs.sh
 ```
 
 Documentation structure follows the [Diátaxis framework](https://diataxis.fr/):

docs-site/README.md

@@ -4,54 +4,42 @@ This directory contains the Starlight-based documentation website for ICP CLI.
 
 ## Overview
 
-The documentation site is built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/), reading markdown files from the `../docs/` directory.
+The documentation site is built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/), reading markdown files directly from the `../docs/` directory.
 
 ## Architecture
 
 ```
 docs-site/
-├── astro.config.mjs     # Starlight configuration (sidebar, theme)
+├── astro.config.mjs       # Starlight configuration (sidebar, theme)
+├── plugins/
+│   └── rehype-rewrite-links.mjs  # Rewrites .md links for Starlight's clean URLs
 ├── src/
 │   ├── content.config.ts  # Content loader configuration
+│   ├── components/        # Custom Starlight component overrides
 │   ├── assets/            # Logo and static assets
 │   └── styles/            # DFINITY theme CSS
-├── public/              # Static files (favicon, etc.)
-└── package.json         # Dependencies and scripts
+├── public/                # Static files (favicon, etc.)
+└── package.json           # Dependencies and scripts
 ```
 
 ## Key Features
 
 ### Content Loading
-- Uses Astro's `glob` loader to read from `../docs/` via a temporary `.docs-temp/` directory
-- Source docs remain plain Markdown (GitHub-friendly)
-- Build process adds frontmatter and processes links automatically
+- Uses Astro's `glob` loader to read directly from `../docs/` (excluding `schemas/` and README files)
+- Source docs use minimal YAML frontmatter (`title` + `description`)
+- A rehype plugin rewrites `.md` links at build time for Starlight's clean URLs
 
 ### Build Pipeline
 
-The build pipeline ensures source documentation remains clean while producing a polished site:
+1. **Starlight** reads content directly from `../docs/` via the glob content loader
+2. **Rehype plugin** (`plugins/rehype-rewrite-links.mjs`) strips `.md` extensions from relative links and adjusts paths for Astro's directory-based output
+3. **DFINITY theme CSS** is applied for consistent branding
+4. **Static HTML** is produced in `dist/`
 
-**Step 1: Prepare Docs** (`../scripts/prepare-docs.sh`)
-- Copies `../docs/` to `.docs-temp/` (excluding `schemas/` directory and README files)
-- Adjusts relative paths and strips `.md` extensions for Starlight's clean URLs
-  - Source files use `.md` extensions (work on GitHub)
-  - Build transforms to clean URLs without `.md` (work on site)
-- Extracts page title from first H1 heading
-- Adds YAML frontmatter with the title
-- Removes the H1 heading from content (prevents duplicate titles)
-
-**Step 2: Starlight Build**
-- Reads content from `.docs-temp/` via glob loader
-- Applies DFINITY theme CSS
-- Generates navigation from manual sidebar configuration
-- Produces static HTML in `dist/`
-
-**Why this approach?**
-- Source docs stay plain Markdown (GitHub-friendly, no framework lock-in)
-- Build-time transformations keep things DRY (single source of truth)
-- Cross-platform compatibility (works on macOS and Linux)
+Source docs use `.md` extensions in links (GitHub-friendly), and the rehype plugin transforms them to clean URLs at build time.
 
 ### Styling
-- Custom CSS copied from `icp-js-sdk-docs` for DFINITY branding
+- Custom CSS for DFINITY branding
 - Files: `layers.css`, `theme.css`, `overrides.css`, `elements.css`
 - Maintains consistent look with other DFINITY documentation sites
 
@@ -60,6 +48,10 @@ The build pipeline ensures source documentation remains clean while producing a
 - Implemented via `rehype-external-links` plugin for content links
 - Custom script in `astro.config.mjs` handles social/header links
 
+### Global Banner
+- A feedback banner is shown on every page via a custom `Banner` component override (`src/components/Banner.astro`)
+- No per-page frontmatter needed — the component renders the same banner globally
+
 ### Navigation
 - Sidebar is **manually configured** in `astro.config.mjs`
 - This is required because Starlight's autogenerate doesn't work with glob loaders
@@ -93,15 +85,14 @@ npm run preview
 ```bash
 npm run clean
 ```
-Removes `.docs-temp/`, `dist/`, and `.astro/` directories
+Removes `dist/` and `.astro/` directories
 
 ## Scripts
 
-- `prepare-docs` - Runs `../scripts/prepare-docs.sh` to prepare documentation files
-- `dev` - Cleans artifacts, prepares docs, and starts development server
-- `build` - Prepares docs and builds for production
+- `dev` - Cleans artifacts and starts development server
+- `build` - Builds for production
 - `preview` - Previews production build locally
-- `clean` - Removes build artifacts (`.docs-temp/`, `dist/`, `.astro/`)
+- `clean` - Removes build artifacts (`dist/`, `.astro/`)
 
 ## Deployment
 
@@ -112,7 +103,7 @@ The site is automatically deployed to GitHub Pages:
 
 The workflow:
 1. Installs dependencies
-2. Runs `npm run build` (which runs `prepare-docs.sh`)
+2. Runs `npm run build`
 3. Uploads the `dist/` directory as a GitHub Pages artifact
 4. Deploys to GitHub Pages
 
@@ -126,7 +117,7 @@ In `astro.config.mjs`:
 - `logo`: ICP logo configuration
 - `favicon`: Site favicon
 - `customCss`: DFINITY theme files
-- `markdown.rehypePlugins`: External link handling with `rehype-external-links`
+- `markdown.rehypePlugins`: Link rewriting and external link handling
 
 ### Sidebar Configuration
 Manual sidebar definition in `astro.config.mjs`:
@@ -148,8 +139,8 @@ The `slug` should match the file path relative to `docs/` without the `.md` exte
 ## Adding New Pages
 
 1. Create a `.md` file in `../docs/` in the appropriate directory
-2. Start with a `# Heading` (used as page title)
-3. Write standard Markdown content
+2. Add YAML frontmatter with `title` and `description`
+3. Write standard Markdown content (no H1 heading — Starlight renders the title)
 4. Add the page to the sidebar in `astro.config.mjs`:
    ```js
    {
@@ -166,21 +157,20 @@ The `slug` should match the file path relative to `docs/` without the `.md` exte
 ### Sidebar shows no pages
 Check that:
 - The file exists in `../docs/` with correct path
+- The file has YAML frontmatter with at least a `title` field
 - The slug in `astro.config.mjs` matches the file path (without `.md`)
 - You ran `npm run dev` to trigger the build process
 
 ### Duplicate page titles
 Check that:
-- The source file in `../docs/` has only one H1 heading
-- The `prepare-docs.sh` script is running correctly
+- The source file in `../docs/` does not have an H1 heading (the `title` frontmatter is rendered as H1 by Starlight)
 
 ### Broken links
 - Use relative links with `.md` extension in source docs: `[text](./file.md)`
-- The build process (`prepare-docs.sh`) adjusts paths and strips `.md` extensions
+- The rehype plugin (`plugins/rehype-rewrite-links.mjs`) strips `.md` extensions and adjusts paths at build time
 - External links should use full URLs
 
 ## Notes
 
-- The `.docs-temp/` directory is generated at build time and should not be committed
-- Source documentation in `../docs/` should never have frontmatter
+- Source documentation in `../docs/` uses minimal YAML frontmatter (`title` + `description`)
 - The `schemas/` directory is excluded from the docs site (served via GitHub raw URLs)

docs-site/astro.config.mjs

@@ -1,6 +1,7 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import rehypeExternalLinks from 'rehype-external-links';
+import rehypeRewriteLinks from './plugins/rehype-rewrite-links.mjs';
 
 // https://astro.build/config
 export default defineConfig({
@@ -11,6 +12,8 @@ export default defineConfig({
   base: process.env.PUBLIC_BASE_PATH || (process.env.NODE_ENV === 'production' ? process.env.PUBLIC_BASE_PREFIX + '/' : '/'),
   markdown: {
     rehypePlugins: [
+      // Rewrite relative .md links for Astro's directory-based output
+      rehypeRewriteLinks,
       // Open external links in new tab
       [rehypeExternalLinks, { target: '_blank', rel: ['noopener', 'noreferrer'] }],
     ],
@@ -22,6 +25,7 @@ export default defineConfig({
       favicon: '/favicon.png',
       components: {
         SiteTitle: './src/components/SiteTitle.astro',
+        Banner: './src/components/Banner.astro',
       },
       head: [
         {