Documentation Site

Astro reading site for the tutorial, with strict TypeScript configuration and npm.

The content collection reads chapters directly from ../docs/ and sorts them by chapter_number. Edit the original Markdown files to update the site. Routes use the chapter filenames, while existing stable content IDs remain unchanged in the sources.

The home page introduces the information-focused approach, groups all chapters into four learning paths, and links to working demonstrations and three complementary presentation packs. Chapter numbers, titles, goals, and URLs come from the existing content collection; only group descriptions and ranges are homepage configuration. It reuses Documentation.astro with an optional wide layout; chapter layouts are unchanged. Homepage styling is in src/styles/home.css. Its local editorial illustration has provenance in assets/illustrations/README.md; it is not a technical diagram. Chapter pages include previous/next links, rendered images, and Mermaid diagrams. Linked Markdown examples, reference notes, and the glossary have reading pages under /materials/. Supporting files and original sources are available under /files/ from an explicit selection of project folders.

The Project Control Center is available at /document-as-code-lab/dashboard/, linked from the chapter menu. By default it reads public/data/project-operations.json, an ignored, versioned snapshot of public GitHub issues, pull requests, main commits, and the latest run of each workflow. Configuration is in src/lib/dashboard/config.ts; presentation styles are in src/styles/dashboard.css. Collection follows pagination links (with a 20-page safety budget); exceeding that budget reports unavailable data rather than an incomplete total. Lists show up to ten matches, while the workflow list shows every retrieved workflow. Activity is a limited feed of the retrieved items.

The Pages workflow generates the snapshot using its read-only GITHUB_TOKEN during the build, then publishes the JSON with the site. Deployments run after pushes to main, manually, and hourly at minute 17. Scheduled runs and CDN updates may be delayed. Snapshot generation time, source revision, and per-source retrieval times are visible. Workflow states describe collection time, so the deploying workflow itself may still be running. There are no data commits or updates to chapter Markdown. GitHub may disable scheduled workflows in inactive public repositories; check Actions if updates stop.

Opening the dashboard, Refresh snapshot, and five-minute visible-tab refreshes read only the published JSON. Fetch live data explicitly calls the anonymous GitHub API once; it does not start API polling. Each source retains its last successful in-memory result on failure. The browser never receives a token. Refresh snapshot also reloads growth measurements. Without GITHUB_TOKEN, local builds reuse an existing snapshot or create an explicitly unavailable placeholder without contacting GitHub. To reproduce collection locally, provide a suitably scoped token through the environment and run node scripts/operational-snapshot.mjs; never put credentials into source files or public assets.

The growth hook also generates ignored public/data/project-metrics.json, schema version 1, using the existing Python measurement rules. It includes generation time, the measured source revision and its commit time, and committed history. The browser fetches this file with cache: no-store, labels it Measured snapshot, and compares it with the retrieved main commit. New measurements become available after a site deployment; they do not update from live API calls. A future independent dataset publisher would need to serve JSON at a public URL with the same schema. Actions artifacts alone are not that public endpoint. Chapter 3 discusses history and provenance and links to the standalone dashboard instead of embedding a second growth widget.

Dashboard verification: npm run test:dashboard checks API normalization, pagination, failures, workflow states, generated schema, provenance, and subpath fetching. It also runs in the Astro pull-request workflow. For browser failure testing of the production build, node scripts/dashboard-test-server.mjs serves an isolated test harness on port 4327 with network fault controls; those controls are never included in the deployed build.

HTML slide decks are listed under /presentations/. YAML in ../presentations/ selects messages and links to the maintained chapters. Four Astro slide components render that content; Reveal.js provides presentation behavior within the same build and deployment. The concept/mechanics and benefits/adoption packs each contain ten slides. Their optional notes fields generate static /presentations/<slug>/notes/ pages linked from the toolbar, index, and homepage; no new slide framework or presenter-window dependency is introduced. See the presentation authoring notes for the format and verification steps. The dedicated theme is src/styles/presentations.css. After a build, run npm run test:homepage for learning-group coverage, pack/notes structure, and retained navigation, alongside the existing content and lesson tests.

The dashboard reference guide’s <!-- interactive: budget-table --> marker mounts BudgetTable.astro. It bundles the official @rhpaiva/cssv 0.5.0 renderer (MIT) and reads examples/dashboards/department-budget.cssv at build time. The file supplies data and table CSS; src/styles/budget-table.css styles the surrounding controls. Our component adds sorting, filtering, and totals, not cell editing or formula evaluation. Only reviewed repository content is loaded. The Markdown table remains as a no-JavaScript/error fallback; keep its values synchronized with the example file. No third-party CDN is required.

Chapters 5, 6, and 8 add optional in-context scenario checks from examples/learning/scenario-checks.json, validated against its JSON Schema at build time. ScenarioCheck.astro shares quiz configuration checks but has no score, tracking, persistence, or network calls. Answers appear after Check answer, with a hint and retry; without JavaScript, a collapsed explanation remains readable. Explicit scenario-check-metadata, scenario-check-traceability, and scenario-check-agent-knowledge markers place the checks near their concepts. Style these, source notes, and reference invitations through src/styles/chapter-learning.css. Run npm run test:scenarios after building.

Chapter 9 adds an Explore change impact action that selects the existing amendment and impact tab, with the same records and traversal as free exploration. No separate guided dataset is maintained.

The tutorial specification register describes the four curriculum groups (1–4, 5–7, 8–9, 10–11) and owner-review gates. It is available under /materials/spec/tutorial/README/, outside chapter numbering. The project source map links authoritative information homes rather than duplicating their rules.

All 11 chapters add quizzes from ../examples/learning/questions.json, mapped to the existing Quiz API. Chapter 4 adds its Markdown playground at the chapter’s practice marker. These are website-only enhancements: the chapter stays in docs/04-markdown.md, with no MDX conversion or duplicated chapter. src/components/learning/ChapterLearning.astro selects the practice content and positions the tools; reusable components are in the same folder. Style them through src/styles/learning.css. The initial components were adapted from the supplied document-as-code-learning.zip. The chapter rewrite package supplies the current quiz questions. Marker names (onboarding-lab, markdown-playground, metadata-lab, processing-lab, chapter-quiz) mount components without MDX; the renderer creates hosts and ChapterLearning.astro moves the corresponding components into them.

The playground uses bundled markdown-it with raw HTML and images disabled, and rejects unsafe link schemes. It does not send input to a server, load learner-entered images, or save edits. Chapter 5 reuses this editor with a practice copy of Contacts and examples/learning/procedure.schema.json. The bundled yaml parser reads the frontmatter; Ajv validates it against that JSON Schema only when Validate metadata is selected. Editing marks the previous check as out of date. The prose preview excludes frontmatter, and malformed or duplicate YAML fields produce errors. The check covers required fields, types, identifier format, allowed statuses, and extra fields, not human approval, prose accuracy, relationships, or cross-file ID uniqueness. Reset restores and checks the initial example. The source, preview, schema, and initial check remain readable without JavaScript. Quiz questions are rendered as accessible fieldsets; single-choice, multiple-choice, and true/false types are supported. Answers are included in the public page, so this is a practice aid, not a secure examination. Responses are not persisted or tracked. Quiz.astro requires a unique id per instance. Run npm run test:learning after building to check scoring, configuration validation, Markdown safety, YAML parsing, schema validation, and lesson mounting; also inspect editing, reset, feedback, and mobile layout in a browser.

From the repository root:

The growth widget also needs Python and the repository’s measurement dependencies. Set up .venv and install requirements.txt as described in the measurement reference. The npm pre-dev and pre-build hooks use that environment when available, otherwise python3; set PYTHON to override the executable. Full Git history is required.

cd site
npm ci
npm run dev

Check and build:

npm run check
npm run build
npm run test:learning
npm run test:content
npm run test:homepage
node scripts/test-budget.mjs

Astro requires Node 22.12 or newer. This project includes Node 22 as a local development dependency, so npm scripts use a compatible runtime even when the system Node version is older. No global Node installation is changed.

Pull requests against main run .github/workflows/astro-pr-check.yml, which installs dependencies with npm ci, checks types, and builds the site. Pushes to main run .github/workflows/deploy-pages.yml, which builds and publishes to GitHub Pages. Required review and build checks must be configured separately in GitHub’s branch rules.

The configured base path is /document-as-code-lab/, including for local development. Build output is written to dist/ and is not committed. The chapter information widget reads metadata from the sources and chapter-specific history from Git at build time; CI checks out full history for this purpose. Its appearance is controlled by src/styles/chapter-information.css.

The standalone dashboard provides the interactive growth view; chapter 3 links to it. The earlier <!-- interactive: project-growth --> component remains available for reuse but is no longer mounted in chapter 3. scripts/growth-report.mjs runs the existing Python measurement with --json-only before development and production builds. The report stays under ignored build/site-growth/; only committed revisions are included. Restart the dev server after a new commit to regenerate it. ProjectGrowth.astro renders the Chart.js view, with CSS in src/styles/project-growth.css. Saved historical charts remain under assets/figures/ and are not rewritten by this change.

Example passages can be enclosed by standalone <!-- example:start onboarding --> and <!-- example:end onboarding --> comments, with blank lines around each marker. Use a matching descriptive identifier for each pair; nesting is not supported. These comments are invisible in GitHub’s Markdown preview. Astro wraps the content in .tutorial-example[data-example="onboarding"], styled by src/styles/tutorial-examples.css. Set --example-accent and --example-background there to change the colors, or use the data attribute to target one example. Keep a visible example heading in the Markdown so its meaning does not depend on color.

Renumbered chapter URLs have static redirects configured in astro.config.mjs. These preserve existing website links while Markdown filenames and navigation follow the new reading order. Chapters 5–7 separate metadata, information architecture, and processing; optional processing experiments are in reference/record-processing.md.

OnboardingLab.astro reads the fixed procedure sources at build time. For chapter 1 it delegates to ProcedureSelectionLab.astro: readers compare approved-only selection with including drafts for review. Sources stay fixed. Excluding draft Contacts leaves the intended three-part handbook incomplete; allowing Contacts permits only a review copy. This is an inclusion preview, not handbook generation or approval. Chapter 5 uses the schema-enabled Markdown editor described above instead of this component.

Chapter 7’s ProcessingPlayground.astro reuses that editor for Contacts, while Access and Equipment remain fixed. Its explicit build validates against the procedure schema, checks unique IDs and nonempty text, and generates a rendered handbook review copy and a draft-procedure review queue. The handbook combines all three procedures, including drafts; the queue selects only drafts. Editing or resetting the source leaves outputs unchanged until a successful build. A failed build preserves the last successful result; the previous successful output is retained separately. Chapter 7 focuses on procedure information and does not mount the employee-readiness simulation.

All simulations are browser-only, without persistence or API calls. They do not invoke Python, edit repository files, approve procedures, or publish a handbook. Sources and initial results remain readable without JavaScript. Run npm run test:learning after a build to check validation, processing, inclusion rules, and lesson mounts. The record-processing reference retains the runnable requirement examples used by later AI and diagram exercises.

The 11-chapter reading order covers information architecture at chapter 6 and workflow automation at chapter 10 and lab architecture at chapter 11. Old chapter URLs redirect directly to their current chapter or the relevant reference guide. The CSSV widget is mounted by the materials route, not a chapter-specific filename. Detailed AI, visual, review, dashboard, publishing, portability, and automation exercises remain under reference/. New conceptual exercises use worked text, diagrams, and quizzes where there is no implemented interactive simulator; they do not expose inactive controls or pretend to call live AI or external systems. Run npm run test:content after a build to verify chapter IDs, diagram sources, routes, links, and assets.

Architecture Explorer

Workflow source links open the maintained files on GitHub. The Pages artifact upload excludes .github, so links under /files/.github/ would return 404 even when the local build contains those files. The content tests reject these unavailable Pages paths.

The production build uses astro build --force to regenerate cached Markdown as well as components. A change to a rendering plugin must reach every chapter even when its Markdown source is unchanged; restoring an older content cache must not preserve obsolete URLs.

Chapter 11 adds a read-only Architecture Explorer through the architecture-explorer marker. Its five curated paths in src/lib/architecture.ts are checked at build time against existing files and the public source-file selection in repositoryFiles(). Only selected implementation files are exposed, not the entire site directory. ArchitectureExplorer.astro supplies a static table; architecture-controller.ts adds tabs with arrow, Home, and End navigation. Style it in src/styles/architecture-explorer.css.

The architecture component never requests APIs, saves data, or starts workflows. Its PDF path leads to workflow artifacts, not a public book. Its dashboard path distinguishes published snapshots from optional live retrieval. The nine-slide lab-architecture deck and notes use the existing presentation pipeline and Pages deployment. Chapters 10 and 11 remain in review. Content, learning, and homepage tests cover source links, quiz mapping, the explorer, and deck structure.

Contract Explorer

Chapter 9 uses the contract-explorer marker and ContractExplorer.astro, registered through the existing chapter learning mechanism. Nine Markdown records under examples/contract-explorer/records/ are authoritative. contract-loader.ts reads them at build time, validates them against schema.json with Ajv, and checks IDs, relation endpoints, references, dates, and cycles. Invalid inputs stop the build. No copied UI dataset or hand-authored graph edges are maintained.

contract-model.ts derives immediate links, delivery coverage via projects, and traversal-based review candidates. contract-controller.ts progressively enhances the static tables and source list with three keyboard-operable views. The graph shows recorded links only; the impact list separately labels derived candidates and their recorded paths. On narrow screens the relationship table replaces the graph. Without JavaScript the record list, source links, commitments, and initial impact paths stay readable. Styles are in src/styles/contract-explorer.css.

Each source link serves the original maintained Markdown bytes through the existing /files/ mechanism, not the transformed snapshot. Details also provide the GitHub repository path, source commit when available, SHA-256 digest, and an explicit uncommitted label for new or edited sources. New GitHub paths become available only after publication. The snapshot is embedded during the Astro build; no API, backend, browser persistence, or AI service is used. Run npm run build then npm run test:contracts to verify transformations, validation failures, source-edit effects, source byte identity, static fallback, and URL prefixes.