Publishing to Websites, Books, and Presentations

In chapter 1, three instruction files became a handbook, a training excerpt, and a dashboard. We have since explored how to structure that information, review changes, and track the work. The next question is how to deliver it to people who need different reading experiences.

A new colleague may want a page they can find quickly on their phone. A trainer needs a sequence of explanations and exercises. A manager may prefer a PDF that can be read offline and referred to during a meeting. These readers can use the same underlying information without receiving the same document.

Publishing is the process of selecting, preparing, checking, and delivering information for an audience. Converting Markdown into another file format is one part of that process. The larger task is deciding what readers need and making the result work for them.

This optional guide uses our onboarding example to plan three publications. It also examines the tutorial’s published website and HTML introduction deck. Reading needs no setup; local build and export activities use the tools identified below.

Read the Lab’s Deployment Triggers

The deployment workflow starts a site build on these events:

on:
  push:
    branches: [main]
  workflow_dispatch:
  schedule:
    - cron: '17 * * * *'

The build job checks out the repository, prepares Python, and invokes the Astro build action. A separate job publishes the built files to GitHub Pages. The hourly trigger refreshes dashboard snapshots; it does not edit chapter sources, and scheduled runs can be delayed.

The workflow file remains authoritative if these settings change. Chapter 10 follows the reader-facing distinction between checks, retained artifacts, and publication.

One Source, Several Reading Experiences

Suppose we want to explain how new colleagues request access, collect equipment, and find their team contacts. We already maintain those instructions separately. We now choose how to use them:

flowchart LR
    source["Shared instructions and visuals"] --> web["Organize for finding information"]
    source --> book["Assemble for continuous reading"]
    source --> training["Adapt for teaching and practice"]
    web --> website["Website"]
    book --> pdf["PDF handbook"]
    training --> slides["Training presentation"]

Reuse the maintained information while shaping each publication for its readers.

The middle step matters. A presentation is not a handbook divided into slides, and a website needs more than a long page of exported text. We keep the facts together while allowing each output to have its own introduction, order, navigation, and visual treatment. The editable Markdown source-and-views diagram also summarizes how readable source can supply configured publishing tools.

Select Files or Extract Sections

Chapter 1 organizes the onboarding instructions as separate files, each containing one procedure. Our handbook script reads all three procedure files and combines their text. The training excerpt uses the complete access procedure and leaves out the other two. Both outputs reuse information at file level.

Sometimes a publication needs only part of a longer file. A publishing tool can extract that section, but it needs a rule for finding where the selection starts and ends. A team might use a heading or explicit markers in the source. Markdown headings alone do not perform that extraction, and renaming a heading may require updating the selection rule.

Files remain the sources we edit and track. Extracting a section does not give it a separate review status or maintenance process. Check that the selected text includes the context readers need, and rebuild and review the output when its source changes. Keep the selection rules with the publishing code so they can be reviewed too.

Our source can also identify example passages with paired HTML comments such as <!-- example:start follow-up --> and <!-- example:end follow-up -->. They are visible in the source, but not shown in GitHub’s Preview view. Astro interprets them to style the enclosed example; they do not automatically extract it into another publication or give it a separate approval status. The site instructions document the convention. Chapter front matter may also describe planned visuals; the contribution guidance explains those project-specific fields.

Our HTML introduction deck uses another approach: its YAML file contains messages written for the session, with references to the source chapters. It does not automatically extract chapter sections. Those references help us identify what to review when a chapter changes, but the slide wording still needs to be updated separately.

Start with whole-file reuse when it meets the reader’s needs. Add section extraction when there is a clear reason to maintain the extra selection rules.

Start with a Publication Brief

Before choosing a publishing tool, describe the intended result. A brief can be short: who will use it, what they should be able to do, which sources it uses, and how you will check it.

For the onboarding presentation, the brief might say:

Prepare a short session for new colleagues on requesting system access. Use the access procedure, explain what information to include, and ask participants to practise writing a request. Leave equipment and contacts for another session. Retain a link to the source so the trainer can check for updates.

The publication-brief template captures these choices for a website, PDF, or presentation. It also records the source version and the person responsible for checking the output. These are our chosen working conventions, not fields mandated by a publishing tool.

Selection needs an explicit rule. Our example handbook includes all three procedures, including draft contacts, because it is a review copy. A publication intended for operational use might require reviewed content only. If an essential section is not ready, decide whether to delay publication or change the publication’s stated scope. Silently removing it could leave readers with an incomplete guide.

Build a Website Around Reader Tasks

A website is useful when people need to find individual topics, follow related information, and return to the current instructions. Organize navigation around their tasks rather than exposing the repository’s folder structure unchanged.

For the onboarding example, the starting page could link to “Request access,” “Collect equipment,” and “Find team contacts.” Each page should make its purpose clear and provide a way back. As the site grows, search, a contents view, and related-topic links can help people find the right detail.

Check a real reader journey: can a new colleague reach the access instructions, understand what to submit, and locate the next relevant topic? Try both a narrow screen and a desktop. Check keyboard navigation, meaningful link text, headings, and image descriptions.

Chapter 1’s linked handbook already gives us a basic reading experience in GitHub. A separate website offers more control over navigation and presentation, but also introduces a build and hosting process to maintain. Generating a website and making it available to readers are separate steps. Decide where it will be hosted and who should have access before publishing project information.

Our Website Uses Astro

We use Astro, a framework for building content-driven websites, to give this tutorial a separate reading experience. The Astro project lives in site/, while the chapter sources remain in docs/. This is a publishing choice, not a requirement of document-as-code; another tool could present the same maintained information.

Our site uses an Astro content collection to read the original Markdown files and their chapter metadata. Layouts and page templates provide the contents view, chapter navigation, and visual styling. The build turns these inputs into web pages and supporting assets. Our site also renders Mermaid diagrams and links to supporting examples. See the Astro documentation and its content collections guide for the underlying concepts.

The responsibilities are separate:

This separation lets us improve navigation or page layout without maintaining another copy of the chapters. An accepted text change can reach the website through a new build. Our HTML presentations now use that same build and deployment process, with their own selected messages and layouts. PDF book and PowerPoint export pipelines are not yet configured.

You can inspect the current reading site locally using the site instructions. From site/, npm run dev starts the local site and npm run build creates production files in site/dist/. Those generated files are not the editable master and are not committed to the repository.

For hosted publication, the intended sequence is: propose a change in a branch, open a pull request, pass the Astro build check, review the change, and merge it into main. A deployment workflow then builds the accepted sources and sends the output to GitHub Pages. Required reviews and checks depend on repository branch rules; a workflow alone does not enforce approval.

The repository is public, and the tutorial website is published on GitHub Pages. The committed deployment workflow builds the accepted sources on pushes to main and publishes the generated output. Successful deployments have been checked in the browser, including chapter navigation, an image, a Mermaid diagram, and the expandable chapter information panel. Enabling Pages and building files are necessary steps; checking the hosted result confirms that readers can use the publication.

Because this is a project website, its address includes /document-as-code-lab/. Navigation, images, and script URLs must work under that path, not just at the root of localhost. Check the published site as well as the local build, including a chapter link, an image, and a Mermaid diagram. A successful build confirms that files were generated; it does not confirm that hosting and browser rendering work.

Assemble a PDF for Continuous Reading

We are developing a small PDF design trial and a proposed practical chapter. It uses Pandoc, Typst, and SVG diagrams from Mermaid CLI. This is separate from the Astro website; the full-book publishing pipeline is not yet implemented.

A PDF provides a stable edition that can be downloaded, shared, or printed. Its structure should help readers understand the material without relying on the surrounding website.

Arrange sections in a deliberate reading order. Add a title, edition information, and enough context to explain the selection. A longer book also needs consistent heading levels, page numbers, a contents page, and useful cross-references. A two-page excerpt may need much less.

Page layout creates problems that are easy to miss in source text. A table can run off the page, a heading can become separated from its paragraph, or a diagram can shrink until its labels are unreadable. Inspect the generated pages, not only the build log. Check that text is selectable and that headings, reading order, and alternative descriptions survive the chosen export process where supported.

For our review handbook, keep the draft label visible inside the PDF. A filename is easily changed or lost when someone forwards the document. Record which source versions produced the edition so that later questions can be answered against the same information.

Design Presentations for the Session

A presentation supports a particular conversation. Decide whether it is an introduction, a workshop, or a technical deep dive before selecting the content.

The access procedure can support a short training sequence:

1. Explain what the colleague needs to include in a request.
2. Show a fictional example containing the system name and team.
3. Ask participants to draft a request and identify which reference they should retain for follow-up.

The underlying instructions stay the same, but the teaching sequence adds explanation and practice. Put supporting detail in speaker notes or a handout rather than shrinking all the text onto a slide. Distinguish examples you create for teaching from facts stated in the source.

AI can help propose the sequence, draft notes, or suggest a visual. Give it the selected source, audience, session purpose, and boundaries, as in chapter 8. Review whether it has invented a service address, response time, or process step that the source does not support.

PowerPoint can remain part of the workflow. Generated slides may provide a starting point for visual refinement, discussion, or delivery. Decide which changes belong only to that presentation and which should return to the maintained content.

Our HTML Presentations Use Astro and Reveal.js

Our first presentation puts these principles into practice. Open the published introduction deck or choose Presentations in the website’s chapter menu. Its eight slides draw on chapters 1, 2, 9, and 10, moving from information reuse through collaboration and review to publishing.

The presentation definition is a YAML file containing the selected messages, slide order, and chapter references. It does not copy entire chapters. The chapters remain the maintained knowledge; the YAML defines a particular teaching sequence.

Unlike the front matter attached to a Markdown record in chapter 5, this standalone YAML file holds structured information on its own. Its opening slide is defined as:

slides:
  - id: introduction
    type: title
    title: Document-as-Code
    subtitle: Maintain the knowledge. Shape the view.
    sources: [docs/01-introduction.md]

title: pairs a field name with its value. The dash starts an item in the slides list, and indentation groups its fields. The brackets in sources contain a list of chapter references. Use spaces, not tabs, for indentation. The excerpt omits other slide fields for clarity.

We separate three responsibilities:

Four reusable slide types support titles, short explanations, comparisons, and workflow diagrams. This lets us improve the layout without rewriting each slide. Reveal.js enhances the pages Astro creates; it is not a separate application or hosting service.

To create a similar deck, add a YAML definition using those slide types and link each slide to its source chapters. The presentation authoring notes describe the fields and verification steps. The existing Astro build discovers the definition and creates a presentation route. Changes merged into main are rebuilt and published through the same GitHub Pages workflow as the documentation.

Source links make the relationship visible, but they do not automatically rewrite a slide when a chapter changes. Review the affected messages and update the YAML when needed. Likewise, rebuilding a deck does not approve its content.

The HTML introduction deck is implemented and published. Speaker notes and presenter mode are not enabled in our integration; the PDF book, workshop deck, and PowerPoint export remain future work.

Reuse Visuals, Adapt Their Presentation

The visual sources guide distinguishes editable sources from their rendered images. Publishing adds another decision: which representation works in each output?

An interactive chart needs a static alternative in a printed book. A detailed diagram may fit a full book page but need simplification for a presentation. A website may let readers enlarge an image; a slide shown across a meeting room cannot rely on that interaction.

The dashboard guide’s budget example demonstrates this distinction with a table. Markdown readers see a saved table; Astro uses the CSSV source to render a styled table with sorting and filtering. The website controls do not belong to the source file, and a static publication needs a readable table without them.

Keep the meaning and source data consistent while adapting size, labels, and detail. Preserve captions, units, source versions, and relevant qualifications. Do not assume that a Mermaid block displayed by GitHub will become a diagram in every exporter. Check the chosen renderer and use a suitable image export when required.

For charts, repeat the dashboard guide’s checks: readable labels, adequate contrast, and an explanation that does not depend on color alone. Review representative images in every target format before scaling up to the full tutorial.

Check Source, Preview, and Target Format

Each check answers a different question. Read the source and diff to check meaning, metadata, and the scope of a change. Use the Markdown preview to check headings, step order, links, and supported diagrams. Inspect each delivered format to check the reader’s experience: a clear paragraph can still be too long for a slide, and a table can be too wide for a PDF page.

GitHub’s Preview view does not run our publishing scripts or render illustrations from our visuals metadata. It also filters HTML for security, so custom scripts and styling from our website may be removed or ignored. The GitHub Flavored Markdown specification describes this processing. Astro can add interactive views because we control its build and website code; those features do not automatically appear in GitHub or a static export.

Check the actual result in every format you publish. Verify headings, table headers, meaningful link text, image descriptions, and navigation. A valid Markdown file or successful build is not evidence that every target format is readable and complete.

Choose Tools with a Small Trial

Start by testing a small but representative selection: headings, a table, a link, and one visual. Add an unusually long title or paragraph to expose layout limits. Compare the effort to produce, check, and maintain the results.

Pandoc is one option for converting Markdown into formats such as HTML, Word, and PowerPoint. PDF generation requires an appropriate rendering engine. Reference documents can influence Word and PowerPoint styling. See the Pandoc user guide.

Quarto is another candidate when the project needs coordinated websites, books, and presentations. Its documentation describes these output types and their configuration. Choosing it would mean adding and maintaining the relevant project settings; its capabilities are not already configured in this repository.

Astro publishes our reading website and, with Reveal.js, our first HTML presentation. Both use the existing GitHub Pages deployment. The PDF book, workshop deck, and file-export pipelines remain to be developed. The onboarding builder still produces Markdown and a chart rather than those formats. Use a small trial to choose additional tools according to the audience, visual requirements, accessibility needs, and maintenance capacity.

Keep Changes Connected to Their Source

Readers will often send feedback in Word, PowerPoint, email, or a meeting. That is compatible with document-as-code, provided there is a clear route back to the maintained information.

If a trainer corrects a factual instruction in a slide, review the correction in the original procedure and rebuild the affected outputs. If the trainer changes a slide’s layout for one event, retain that in the presentation’s design source or reference template. If the change is a local teaching example, decide whether other trainers would benefit from maintaining it as reusable material.

Repeated manual changes to generated files will be lost when those files are rebuilt unless the changes are incorporated into the process. Record presentation-specific additions alongside their source references, and avoid letting an exported document become an untracked competing master.

For each release, retain the selected inputs, their order, the source revision, tool versions, relevant settings, and the exact outputs reviewed. Local uncommitted edits need to be accounted for too; a commit identifier alone does not describe them. The review and collaboration guide explains how a review record connects evidence to a decision.

Try It: Prepare Three Publications

Use a disposable copy of the project for source edits so the fixed examples in chapter 1 remain unchanged. Begin with the onboarding source files, handbook review copy, and training excerpt.

1. Make three working copies of the publication brief: one for a website, one for a PDF handbook, and one for an access-training presentation.
2. Identify the audience, purpose, and ordered sources for each. Label all three as fictional teaching material. Explain whether contacts is included and how its draft status affects the publication.
3. Sketch the website navigation and the PDF reading order. Write a three-slide teaching outline based on the access procedure. Keep these plans alongside the briefs.
4. In the disposable project copy, add a clearly fictional clarification to the access instructions. Record the exact edit. With the Python environment described in the measurement reference active, run python scripts/build_onboarding_showcase.py from that copy’s root.
5. Inspect the regenerated handbook and training excerpt. Both should contain the clarification; the status chart should retain its counts because no status changed. Update the presentation outline if the teaching sequence needs to explain the clarification.
6. Record which outputs changed, which remained unchanged, and what still requires an actual format-specific export and visual check.

Expected result: three publication briefs, an output-specific structure for each, and a demonstrated source change reaching the two existing text outputs. This core exercise prepares the publishing decisions; it does not yet produce a website, PDF, or PowerPoint file.

If an output seems stale: confirm that you ran the builder in the disposable copy and opened files from that same copy. Check the selected source filenames and compare the generated text with your recorded edit.

Keep: the briefs, teaching outline, source-change note, and review observations. Do not replace the tutorial’s fixed examples with your fictional variation.

Extend It: Export and Inspect

When you are ready to try a converter, follow the official Pandoc installation guide. The following is an optional trial, not a verified pipeline supplied by this project.

In your disposable project copy, create build/publishing/. Save the three-slide outline as build/publishing/slides.md, using a level-one heading for each slide. From the project root, try:

pandoc assets/onboarding-showcase/handbook.md --standalone --metadata title="Onboarding review copy" -o build/publishing/handbook.html
pandoc assets/onboarding-showcase/handbook.md -o build/publishing/handbook.pdf
pandoc build/publishing/slides.md --slide-level=1 -o build/publishing/training.pptx

The PDF command requires a PDF engine configured for Pandoc; see its PDF guidance. These commands produce local files, not a hosted website or a released publication. The HTML trial is a single reading page rather than the multi-page website in your brief.

Open each successful output and compare it with the brief. Check page breaks in the PDF, text fit in the slides, and headings and links in the HTML. Confirm that the source clarification is present wherever it belongs. Record converter versions and checks, including any failed or untested format. A successful conversion is the starting point for this review.

Chapter 11, Behind the Lab, traces this tutorial’s implementation and compares it with a Microsoft 365 alternative. The portable workflow guide develops that alternative in more detail.