corvus-docs-website

name

corvus-docs-website

description

Build, serve, and maintain the Corvus.Text.Json documentation website and the six Blazor WASM playgrounds (JSON Schema, JSONata, JMESPath, JsonLogic, JSONPath, YAML). Covers the 12-step build.ps1 pipeline (steps 0-11, with sub-steps), generated vs hand-authored file boundaries, incremental rebuild patterns, XmlDocToMarkdown API doc generation, SCSS/JS asset compilation, and playground startup with Monaco editor. USE FOR: building or previewing the docs site, modifying website content or theme, updating API documentation, running or modifying playgrounds. DO NOT USE FOR: library development (use other skills).

Documentation Website and Playgrounds

Documentation Website

Location

Source: docs/website/site/ Build output: docs/website/.output/

Building

cd docs\website
.\build.ps1

The build script runs a 12-step pipeline (steps 0-11, with sub-steps like 1a/1b, 9b-9f) compiling content, SCSS, taxonomy, and API docs into .output/.

Serving Locally

# Preview the built site
cd docs\website
.\preview.ps1
# Or:
.\build.ps1 -ServeOnly

⚠️ CRITICAL: Stop the Server Before Rebuilding

The build script deletes and recreates .output/. On Windows, the Node file server holds file locks that prevent deletion, causing the build to hang indefinitely. Always stop the serving process before running build.ps1.

Generated vs Hand-Authored Files

Auto-generated (by build.ps1, .gitignored):

• site/theme/corvus/views/api/v5/index.cshtml and v4/index.cshtml
• site/theme/corvus/views/Shared/_ApiSidebarV5.cshtml and V4
• site/content/Api-v5/, site/content/Api-v4/ (except namespaces/ and examples/)
• site/taxonomy/api-v5/, site/taxonomy/api-v4/
• site/content/Docs/, site/content/Examples/
• site/taxonomy/docs/, site/taxonomy/examples/

Hand-authored (committed):

• site/source/ — copied into target tree by build step 0
• site/content/GettingStarted/, site/content/Home/
• site/content/Api-v5/namespaces/, site/content/Api-v5/examples/
• Theme SCSS, JS, layout views

Incremental Rebuilds

Changed	Re-run
SCSS styles	npx sass theme\corvus\assets\css\scss\main.scss .output\main.css --style=compressed --no-source-map
JavaScript	Copy-Item theme\corvus\assets\js\*.js .output\
Content markdown	Steps 3-6 of build.ps1
Library source code	dotnet build the library, then regenerate API docs
API page templates	Rebuild XmlDocToMarkdown tool + regenerate

XmlDocToMarkdown Tool

Located at docs/website/tools/XmlDocToMarkdown/. Processes XML doc comments + assemblies into:

• Markdown content files
• Taxonomy YAML
• Razor views
• Per-type HTML pages

Supports multi-assembly input, versioned output with engine switcher, and per-version search indices.

Playgrounds

Six Blazor WASM playgrounds with Monaco editor integration:

Playground	Directory	Port
JSON Schema	docs/playground/	5281
JSONata	docs/playground-jsonata/	5280
JMESPath	docs/playground-jmespath/	—
JsonLogic	docs/playground-jsonlogic/	—
JSONPath	docs/playground-jsonpath/	—
YAML	docs/playground-yaml/	—

Running a Playground

# 1. Build the JS bundle (only after changing JS/Monaco assets)
cd docs\playground-jsonata
npm ci
npm run bundle

# 2. Start the Blazor WASM dev server on a fixed port
$env:ASPNETCORE_URLS = "http://127.0.0.1:5280"
dotnet run --project src\Corvus.Text.Json.Jsonata.Playground\Corvus.Text.Json.Jsonata.Playground.csproj

Use ASPNETCORE_URLS env var to pin the port — --urls flag does not work with the WASM app host.

SR.Format WASM Bug

SR.Format does not work correctly in Blazor WASM because System.Resources.UseSystemResourceKeys returns true, causing string.Join fallback. The EvaluationService.FixBrokenSRFormat() method compensates. All exception messages displayed to the user must go through this method.

Cross-References

• For building the library (prerequisite for API docs), see corvus-build-and-test
• See docs/website/DEVELOPMENT.md for the full development guide

CI Pipeline

In CI, the website build runs as a post-compile job, in parallel with tests and packaging. This avoids adding ~13 minutes to the critical compile step.

• Compile phase (build.ps1) — sets BUILDVAR_BuildWebsite=false to skip the website build during the main compile.
• Post-compile phase (build-website.ps1) — restores the compile cache and runs docs/website/build.ps1 -SkipDotNetBuild, using pre-built assemblies and XML docs from the compile phase. Reads BUILDVAR_BasePathPrefix and BUILDVAR_IsPreviewDeployment from environment variables.
• Deploy jobs — download the website output artifact produced by the post-compile job.

The parallel structure is enabled by the postCompileScript input in the reusable workflow (endjin/Endjin.RecommendedPractices.GitHubActions).

For local development, run docs/website/build.ps1 directly (it builds the .NET solution as part of its pipeline unless -SkipDotNetBuild is passed).