Document-as-Code Lab | Behind the architecture

The tutorial is built the way it teaches

Maintained sources become a website, interactive applications, and presentations

We maintain information before choosing a view

One repository separates the information from the software that presents it

  • docs/ and reference/ hold Markdown chapters and guides
  • examples/ holds structured fictional records
  • presentations/ holds slide-deck messages and chapter references
  • site/ holds Astro layouts and interactive components

Git records changes; GitHub supports collaboration

Maintained information

  • Source files and structured records
  • Versions and diffs
  • Reviewable changes

Repository workflow

  • Pull requests for proposed edits
  • Checks from GitHub Actions
  • Merge and deployment under configured rules

Astro turns sources into a readable website

The same build assembles HTML pages and the code for browser interaction

  1. 01

    Read

    Markdown, record data, and presentation YAML

  2. 02

    Assemble

    Astro layouts and reusable components

  3. 03

    Build

    HTML, CSS, JavaScript, images, and data

  4. 04

    Publish

    GitHub Pages serves the built files

  • Chapter pages
  • Interactive labs
  • HTML slide decks

Static hosting can deliver interactive applications through browser JavaScript.

The browser can explore information without owning it

Interactive components change the experience, not the authoritative source

  • Chapter exercises simulate editing and processing in the browser
  • The Contract Explorer reads build-time data from validated Markdown records
  • The dashboard presents published snapshots and optional live retrieval
  • Readers can inspect source links and revisions

Presentations reuse knowledge without copying a chapter

YAML defines the teaching sequence; Astro and Reveal.js render the slides

  • Short messages reference the maintained chapters
  • Reusable slide components establish a consistent format
  • HTML decks and speaker-note pages share the site build
  • Presentation wording still needs editorial review after source changes

GitHub Actions runs the pipeline; Pages serves the result

A successful build and a published website are distinct results

  1. 01

    PR

    Check proposed changes without publishing

  2. 02

    Main

    Trigger the deployment workflow on a push

  3. 03

    Build

    Astro generates the deployable site

  4. 04

    Deploy

    GitHub Pages receives the built files

  • Check results
  • Artifacts
  • Public website

Other workflows generate growth reports and PDF proof artifacts without publishing them as pages.

The principles work beyond GitHub

This tutorial

  • Markdown in GitHub
  • Pull requests and Actions
  • Astro on GitHub Pages

Possible Microsoft 365 workflow

  • Word and Excel in SharePoint or OneDrive
  • File history, review, Power Automate
  • Copilot and authorized agent tools

Build an environment around useful information

Choose maintained sources, make changes inspectable, and deliver more than one view

  • Identify ownership and the authoritative source
  • Add structure, relationships, and checks where useful
  • Automate repeatable work; review meaningful changes
  • Let the tools follow the need, not the other way around