FreeCampus Python

Build a Documentation Site with Quarto

Organize a multi-page Quarto website, configure reader-focused navigation and cross-references, diagnose render failures, and inspect the clean HTML artifact.

python-foundations documentation-publishing quarto documentation-sites

↗ Open in Colab

• Level: Beginner
• Estimated time: 3.5–5 hours
• You will learn: Turn QMD source and project configuration into a complete, navigable documentation site and repair failures using file, line, link, and output evidence.
• Practice in: A local Midnight Museum Quarto project; Colab is a reading companion rather than the site builder

Open this lesson in Google Colab

A documentation site is not a pile of HTML files written by hand. Source pages, project configuration, navigation, assets, and a renderer combine into an output artifact. The source belongs in version control; the generated _site directory can be rebuilt and published after its checks pass.

This lesson asks:

1. Which files are source, configuration, cache, and public output?
2. How should navigation reflect reader tasks rather than alphabetical filenames?
3. Why should internal links point to QMD source paths?
4. When is preview useful, and why must deployment use a complete render?
5. How do you locate a failure in YAML, a page, a cross-reference, or generated output?

1. Separate source from rendered output

Use this learner-sized project:

midnight-museum/
├── README.md
├── pyproject.toml
├── src/museum_quest/
├── tests/
└── docs/
    ├── _quarto.yml
    ├── index.qmd
    ├── tutorial.qmd
    ├── how-to-rank-exhibits.qmd
    ├── why-ranking-is-deterministic.qmd
    ├── api.qmd
    └── images/
        └── reader-paths.svg

After a render, Quarto creates:

docs/
├── .quarto/          # local project state/cache
└── _site/            # generated public artifact
    ├── index.html
    ├── tutorial.html
    ├── how-to-rank-exhibits.html
    ├── why-ranking-is-deterministic.html
    ├── api.html
    ├── search.json
    └── site_libs/

Do not hand-edit _site/api.html to fix source content. The next render will replace the edit. Find the owning QMD file or project configuration, repair it, and render again.

Quarto transforms reviewed source and configuration into a replaceable site artifact.

flowchart LR
  A[QMD and Markdown source] --> D[Quarto render]
  B[_quarto.yml] --> D
  C[Images and styles] --> D
  D --> E[_site HTML artifact]
  E --> F[Inspection]
  F --> G[Publication]

Create the smallest useful project file

Place _quarto.yml inside docs/:

project:
  type: website
  output-dir: _site

website:
  title: Midnight Museum Quest
  page-navigation: true
  sidebar:
    contents:
      - index.qmd
      - tutorial.qmd
      - how-to-rank-exhibits.qmd
      - why-ranking-is-deterministic.qmd
      - api.qmd

format:
  html:
    toc: true

Read the fields by responsibility:

• project.type tells Quarto to build a website rather than unrelated documents.
• output-dir gives generated files one replaceable boundary.
• website.title labels the site.
• page-navigation adds previous/next movement through the declared order.
• sidebar.contents owns visible page sequence.
• format.html.toc gives longer pages local heading navigation.

YAML indentation carries structure. contents belongs under sidebar, which belongs under website. Use spaces consistently; do not use tabs.

Checkpoint: identify the owning file

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const progress = document.createElement("div");
  progress.className = "fcpython-quiz-progress";

  const counter = document.createElement("p");
  counter.className = "fcpython-quiz-counter";
  counter.setAttribute("aria-live", "polite");
  progress.appendChild(counter);

  const tabs = document.createElement("div");
  tabs.className = "fcpython-quiz-steps";
  tabs.setAttribute("role", "tablist");
  tabs.setAttribute("aria-label", "Quiz questions");
  progress.appendChild(tabs);
  container.appendChild(progress);

  const questions = document.createElement("div");
  questions.className = "fcpython-quiz-questions";

  const feedbackNodes = [];
  const questionPanels = [];
  const stepButtons = [];
  let currentQuestion = 0;

  function setStepStatus(questionIndex, status) {
    const step = stepButtons[questionIndex];
    const question = quiz.questions[questionIndex];
    const statuses = {
      answered: "answered",
      correct: "correct",
      incorrect: "incorrect",
      unanswered: "not answered",
    };

    step.classList.remove(
      "is-answered",
      "is-correct",
      "is-incorrect",
      "is-unanswered"
    );
    if (status) {
      step.classList.add(`is-${status}`);
    }

    const statusLabel = status ? `, ${statuses[status]}` : "";
    step.setAttribute(
      "aria-label",
      `Question ${questionIndex + 1}: ${question.prompt}${statusLabel}`
    );
  }

  function showQuestion(questionIndex, focusPanel = false) {
    currentQuestion = Math.max(
      0,
      Math.min(questionIndex, quiz.questions.length - 1)
    );

    questionPanels.forEach((panel, index) => {
      panel.hidden = index !== currentQuestion;
    });
    stepButtons.forEach((step, index) => {
      const isCurrent = index === currentQuestion;
      step.classList.toggle("is-current", isCurrent);
      step.setAttribute("aria-selected", String(isCurrent));
      step.tabIndex = isCurrent ? 0 : -1;
    });

    counter.textContent = `Question ${currentQuestion + 1} of ${quiz.questions.length}`;

    const selected = questionPanels[currentQuestion].querySelector(
      "input[type='radio']:checked"
    );
    const isLastQuestion = currentQuestion === quiz.questions.length - 1;
    previous.hidden = currentQuestion === 0;
    next.hidden = isLastQuestion || !selected;
    check.hidden = !isLastQuestion;

    if (focusPanel) {
      questionPanels[currentQuestion].focus();
    }
  }

  quiz.questions.forEach((question, questionIndex) => {
    const tabId = `${quiz.id}-question-tab-${questionIndex + 1}`;
    const panelId = `${quiz.id}-question-panel-${questionIndex + 1}`;

    const step = document.createElement("button");
    step.type = "button";
    step.className = "fcpython-quiz-step";
    step.id = tabId;
    step.textContent = String(questionIndex + 1);
    step.setAttribute("role", "tab");
    step.setAttribute("aria-controls", panelId);
    step.setAttribute("aria-selected", "false");
    step.tabIndex = -1;
    step.addEventListener("click", () => showQuestion(questionIndex));
    step.addEventListener("keydown", (event) => {
      let destination = null;
      if (event.key === "ArrowRight") {
        destination = (questionIndex + 1) % quiz.questions.length;
      } else if (event.key === "ArrowLeft") {
        destination =
          (questionIndex - 1 + quiz.questions.length) % quiz.questions.length;
      } else if (event.key === "Home") {
        destination = 0;
      } else if (event.key === "End") {
        destination = quiz.questions.length - 1;
      }

      if (destination !== null) {
        event.preventDefault();
        showQuestion(destination);
        stepButtons[destination].focus();
      }
    });
    stepButtons.push(step);
    tabs.appendChild(step);
    setStepStatus(questionIndex, "");

    const panel = document.createElement("div");
    panel.className = "fcpython-quiz-panel";
    panel.id = panelId;
    panel.setAttribute("role", "tabpanel");
    panel.setAttribute("aria-labelledby", tabId);
    panel.tabIndex = -1;

    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = question.prompt;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);
      input.addEventListener("change", () => {
        setStepStatus(questionIndex, "answered");
        feedbackNodes[questionIndex].textContent = "";
        feedbackNodes[questionIndex].className = "fcpython-quiz-feedback";
        score.textContent = "";
        showQuestion(questionIndex);
      });

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    panel.appendChild(fieldset);
    questionPanels.push(panel);
    questions.appendChild(panel);
  });

  container.appendChild(questions);

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const previous = document.createElement("button");
  previous.type = "button";
  previous.className = "fcpython-quiz-secondary";
  previous.textContent = "Previous";
  previous.addEventListener("click", () => {
    showQuestion(currentQuestion - 1, true);
  });

  const next = document.createElement("button");
  next.type = "button";
  next.textContent = "Next question";
  next.addEventListener("click", () => {
    showQuestion(currentQuestion + 1, true);
  });

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.className = "fcpython-quiz-secondary fcpython-quiz-reset";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;
    let firstQuestionToReview = null;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        setStepStatus(questionIndex, "unanswered");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
        setStepStatus(questionIndex, "correct");
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
        setStepStatus(questionIndex, "incorrect");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
    if (firstQuestionToReview !== null) {
      showQuestion(firstQuestionToReview, true);
    }
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    stepButtons.forEach((_, questionIndex) => {
      setStepStatus(questionIndex, "");
    });
    score.textContent = "";
    showQuestion(0, true);
  });

  actions.appendChild(previous);
  actions.appendChild(next);
  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  showQuestion(0);
  return container;
}

2. Give each page an informative entrance

A minimal QMD page uses YAML front matter and meaningful headings:

---
title: Rank Your First Museum Exhibit
description: Follow a guided path from a clean project to one verified score.
---

## Before the museum opens

Use Python 3.10 or newer and complete the project installation.

## Rank the Moon Dial

```python
from museum_quest import rank_exhibit

result = rank_exhibit("Moon Dial", votes=4, minutes_open=75)
print(result)
```

Expected result: `ExhibitScore(name='Moon Dial', score=44)`.

The title becomes the page heading and default navigation label. The description can support previews and metadata. The page itself retains the reader-focused prerequisites, action, and expected result from Lesson 2.

Quarto features should clarify the task. A normal note uses a callout:

::: {.callout-note title="Why 75 minutes adds four points"}
Only complete 30-minute periods count. Seventy-five minutes contains two
complete periods.
:::

Do not put every paragraph into a colored box. Reserve callouts for information whose role—note, tip, warning, important point—helps a reader decide how to use it.

Link to source pages, not generated filenames

From tutorial.qmd, link to a sibling source:

[Look up the `rank_exhibit` contract](api.qmd "API reference")

Quarto resolves that source link to the appropriate output. A direct api.html link binds the source to one output format and is easier to break if the project later becomes a book or another format.

From root README.md, the same target uses its actual relative depth:

[Look up the `rank_exhibit` contract](docs/api.qmd "API reference")

Paths are relative to the page containing them, not to whichever terminal the author happens to use.

3. Design navigation around reader movement

The flat list works for five pages. Labels make the purpose even clearer:

website:
  title: Midnight Museum Quest
  page-navigation: true
  search: true
  sidebar:
    style: floating
    contents:
      - href: index.qmd
        text: Start Here
      - href: tutorial.qmd
        text: Guided Museum Visit
      - href: how-to-rank-exhibits.qmd
        text: Change a Ranking
      - href: why-ranking-is-deterministic.qmd
        text: Why Rankings Repeat
      - href: api.qmd
        text: Public API

The order moves from entry to guided use, focused task, understanding, and exact lookup. Alphabetical order would begin with API, not the most useful entrance.

For a larger site, sections can group related pages:

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Start Here
      - section: Learn
        contents:
          - tutorial.qmd
      - section: Use the Package
        contents:
          - how-to-rank-exhibits.qmd
          - why-ranking-is-deterministic.qmd
          - api.qmd

Avoid creating a one-page section under every documentation type. A hierarchy should reduce choice, not make every click reveal another nearly empty menu.

Search helps when the site has enough content and readers know the term to find. It does not replace a clear entry journey for someone who does not yet know the function name.

Repository actions create feedback paths

A published project can expose edit and issue actions:

website:
  repo-url: https://github.com/example/midnight-museum
  repo-actions:
    - edit
    - issue

Use the real repository URL. A feedback link without ownership or response expectations is not a complete support plan, but it gives readers an observable route to report stale content.

Checkpoint: organize the reader path

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const progress = document.createElement("div");
  progress.className = "fcpython-quiz-progress";

  const counter = document.createElement("p");
  counter.className = "fcpython-quiz-counter";
  counter.setAttribute("aria-live", "polite");
  progress.appendChild(counter);

  const tabs = document.createElement("div");
  tabs.className = "fcpython-quiz-steps";
  tabs.setAttribute("role", "tablist");
  tabs.setAttribute("aria-label", "Quiz questions");
  progress.appendChild(tabs);
  container.appendChild(progress);

  const questions = document.createElement("div");
  questions.className = "fcpython-quiz-questions";

  const feedbackNodes = [];
  const questionPanels = [];
  const stepButtons = [];
  let currentQuestion = 0;

  function setStepStatus(questionIndex, status) {
    const step = stepButtons[questionIndex];
    const question = quiz.questions[questionIndex];
    const statuses = {
      answered: "answered",
      correct: "correct",
      incorrect: "incorrect",
      unanswered: "not answered",
    };

    step.classList.remove(
      "is-answered",
      "is-correct",
      "is-incorrect",
      "is-unanswered"
    );
    if (status) {
      step.classList.add(`is-${status}`);
    }

    const statusLabel = status ? `, ${statuses[status]}` : "";
    step.setAttribute(
      "aria-label",
      `Question ${questionIndex + 1}: ${question.prompt}${statusLabel}`
    );
  }

  function showQuestion(questionIndex, focusPanel = false) {
    currentQuestion = Math.max(
      0,
      Math.min(questionIndex, quiz.questions.length - 1)
    );

    questionPanels.forEach((panel, index) => {
      panel.hidden = index !== currentQuestion;
    });
    stepButtons.forEach((step, index) => {
      const isCurrent = index === currentQuestion;
      step.classList.toggle("is-current", isCurrent);
      step.setAttribute("aria-selected", String(isCurrent));
      step.tabIndex = isCurrent ? 0 : -1;
    });

    counter.textContent = `Question ${currentQuestion + 1} of ${quiz.questions.length}`;

    const selected = questionPanels[currentQuestion].querySelector(
      "input[type='radio']:checked"
    );
    const isLastQuestion = currentQuestion === quiz.questions.length - 1;
    previous.hidden = currentQuestion === 0;
    next.hidden = isLastQuestion || !selected;
    check.hidden = !isLastQuestion;

    if (focusPanel) {
      questionPanels[currentQuestion].focus();
    }
  }

  quiz.questions.forEach((question, questionIndex) => {
    const tabId = `${quiz.id}-question-tab-${questionIndex + 1}`;
    const panelId = `${quiz.id}-question-panel-${questionIndex + 1}`;

    const step = document.createElement("button");
    step.type = "button";
    step.className = "fcpython-quiz-step";
    step.id = tabId;
    step.textContent = String(questionIndex + 1);
    step.setAttribute("role", "tab");
    step.setAttribute("aria-controls", panelId);
    step.setAttribute("aria-selected", "false");
    step.tabIndex = -1;
    step.addEventListener("click", () => showQuestion(questionIndex));
    step.addEventListener("keydown", (event) => {
      let destination = null;
      if (event.key === "ArrowRight") {
        destination = (questionIndex + 1) % quiz.questions.length;
      } else if (event.key === "ArrowLeft") {
        destination =
          (questionIndex - 1 + quiz.questions.length) % quiz.questions.length;
      } else if (event.key === "Home") {
        destination = 0;
      } else if (event.key === "End") {
        destination = quiz.questions.length - 1;
      }

      if (destination !== null) {
        event.preventDefault();
        showQuestion(destination);
        stepButtons[destination].focus();
      }
    });
    stepButtons.push(step);
    tabs.appendChild(step);
    setStepStatus(questionIndex, "");

    const panel = document.createElement("div");
    panel.className = "fcpython-quiz-panel";
    panel.id = panelId;
    panel.setAttribute("role", "tabpanel");
    panel.setAttribute("aria-labelledby", tabId);
    panel.tabIndex = -1;

    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = question.prompt;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);
      input.addEventListener("change", () => {
        setStepStatus(questionIndex, "answered");
        feedbackNodes[questionIndex].textContent = "";
        feedbackNodes[questionIndex].className = "fcpython-quiz-feedback";
        score.textContent = "";
        showQuestion(questionIndex);
      });

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    panel.appendChild(fieldset);
    questionPanels.push(panel);
    questions.appendChild(panel);
  });

  container.appendChild(questions);

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const previous = document.createElement("button");
  previous.type = "button";
  previous.className = "fcpython-quiz-secondary";
  previous.textContent = "Previous";
  previous.addEventListener("click", () => {
    showQuestion(currentQuestion - 1, true);
  });

  const next = document.createElement("button");
  next.type = "button";
  next.textContent = "Next question";
  next.addEventListener("click", () => {
    showQuestion(currentQuestion + 1, true);
  });

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.className = "fcpython-quiz-secondary fcpython-quiz-reset";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;
    let firstQuestionToReview = null;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        setStepStatus(questionIndex, "unanswered");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
        setStepStatus(questionIndex, "correct");
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
        setStepStatus(questionIndex, "incorrect");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
    if (firstQuestionToReview !== null) {
      showQuestion(firstQuestionToReview, true);
    }
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    stepButtons.forEach((_, questionIndex) => {
      setStepStatus(questionIndex, "");
    });
    score.textContent = "";
    showQuestion(0, true);
  });

  actions.appendChild(previous);
  actions.appendChild(next);
  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  showQuestion(0);
  return container;
}

4. Use cross-references when they reduce hunting

A figure with an identifier can be referenced by name:

![The README branches to tutorial, how-to, explanation, and API pages.](images/reader-paths.svg){#fig-reader-paths}

The four destinations in @fig-reader-paths answer different reader questions.

Quarto requires a type prefix such as fig-, tbl-, or lst-. Use hyphens in identifiers and keep them stable when other pages link to them.

A table can carry a caption and ID:

| Reader | Destination |
|---|---|
| New learner | Tutorial |
| Active caller | API reference |

: Reader questions choose documentation paths {#tbl-reader-paths}

Reference it as @tbl-reader-paths. The rendered number and link update if the table moves.

Do not cross-reference every short code block. A nearby sentence may be easier than “see Listing 14.” Use a reference when a reader needs to find or revisit a named object.

Diagnose an unresolved reference

Suppose the render warns that @fig-reader_path cannot be resolved. Compare the reference with the label:

Reference: @fig-reader_path
Label:     #fig-reader-paths

There are two differences: underscore versus hyphen, and singular versus plural. Repair the source reference to the exact stable ID, then perform a full render and follow the link in HTML.

5. Preview quickly, render completely

From the docs/ project directory:

quarto preview

Preview starts a local server and rerenders affected pages while you work. It is useful for checking headings, navigation, and layout in a browser. Stop the server before treating its current screen as a deployable artifact.

From the repository root, target the project explicitly:

quarto render docs

A successful full render reports an output such as:

Output created: _site/index.html

When the project root is docs/, _site is normally docs/_site. Read paths in context instead of copying one output line into every project.

Why render again after preview?

• a page may never have been opened during preview;
• changes to _quarto.yml, shared includes, styles, or navigation affect more than the active page;
• caches can preserve state that a clean build will not have; and
• publication needs one complete artifact tied to reviewed source.

Clean generated output safely, rerender, and compare the named page inventory. Generated _site can be removed; QMD source cannot.

Checkpoint: choose preview or render

{
  const scripts = Array.from(
    document.querySelectorAll("script.fcpython-ojs-quiz-config")
  );
  const script = scripts.find(
    (node) => node.dataset.fcpythonRendered !== "true"
  );

  if (!script) {
    return html`<div class="fcpython-quiz fcpython-quiz-warning">
      Quiz configuration was not found.
    </div>`;
  }

  script.dataset.fcpythonRendered = "true";
  const quiz = JSON.parse(script.textContent);
  const container = html`<div class="fcpython-quiz"></div>`;
  const title = document.createElement("h3");
  title.textContent = quiz.title;
  container.appendChild(title);

  const instructions = document.createElement("p");
  instructions.textContent = quiz.instructions;
  container.appendChild(instructions);

  const progress = document.createElement("div");
  progress.className = "fcpython-quiz-progress";

  const counter = document.createElement("p");
  counter.className = "fcpython-quiz-counter";
  counter.setAttribute("aria-live", "polite");
  progress.appendChild(counter);

  const tabs = document.createElement("div");
  tabs.className = "fcpython-quiz-steps";
  tabs.setAttribute("role", "tablist");
  tabs.setAttribute("aria-label", "Quiz questions");
  progress.appendChild(tabs);
  container.appendChild(progress);

  const questions = document.createElement("div");
  questions.className = "fcpython-quiz-questions";

  const feedbackNodes = [];
  const questionPanels = [];
  const stepButtons = [];
  let currentQuestion = 0;

  function setStepStatus(questionIndex, status) {
    const step = stepButtons[questionIndex];
    const question = quiz.questions[questionIndex];
    const statuses = {
      answered: "answered",
      correct: "correct",
      incorrect: "incorrect",
      unanswered: "not answered",
    };

    step.classList.remove(
      "is-answered",
      "is-correct",
      "is-incorrect",
      "is-unanswered"
    );
    if (status) {
      step.classList.add(`is-${status}`);
    }

    const statusLabel = status ? `, ${statuses[status]}` : "";
    step.setAttribute(
      "aria-label",
      `Question ${questionIndex + 1}: ${question.prompt}${statusLabel}`
    );
  }

  function showQuestion(questionIndex, focusPanel = false) {
    currentQuestion = Math.max(
      0,
      Math.min(questionIndex, quiz.questions.length - 1)
    );

    questionPanels.forEach((panel, index) => {
      panel.hidden = index !== currentQuestion;
    });
    stepButtons.forEach((step, index) => {
      const isCurrent = index === currentQuestion;
      step.classList.toggle("is-current", isCurrent);
      step.setAttribute("aria-selected", String(isCurrent));
      step.tabIndex = isCurrent ? 0 : -1;
    });

    counter.textContent = `Question ${currentQuestion + 1} of ${quiz.questions.length}`;

    const selected = questionPanels[currentQuestion].querySelector(
      "input[type='radio']:checked"
    );
    const isLastQuestion = currentQuestion === quiz.questions.length - 1;
    previous.hidden = currentQuestion === 0;
    next.hidden = isLastQuestion || !selected;
    check.hidden = !isLastQuestion;

    if (focusPanel) {
      questionPanels[currentQuestion].focus();
    }
  }

  quiz.questions.forEach((question, questionIndex) => {
    const tabId = `${quiz.id}-question-tab-${questionIndex + 1}`;
    const panelId = `${quiz.id}-question-panel-${questionIndex + 1}`;

    const step = document.createElement("button");
    step.type = "button";
    step.className = "fcpython-quiz-step";
    step.id = tabId;
    step.textContent = String(questionIndex + 1);
    step.setAttribute("role", "tab");
    step.setAttribute("aria-controls", panelId);
    step.setAttribute("aria-selected", "false");
    step.tabIndex = -1;
    step.addEventListener("click", () => showQuestion(questionIndex));
    step.addEventListener("keydown", (event) => {
      let destination = null;
      if (event.key === "ArrowRight") {
        destination = (questionIndex + 1) % quiz.questions.length;
      } else if (event.key === "ArrowLeft") {
        destination =
          (questionIndex - 1 + quiz.questions.length) % quiz.questions.length;
      } else if (event.key === "Home") {
        destination = 0;
      } else if (event.key === "End") {
        destination = quiz.questions.length - 1;
      }

      if (destination !== null) {
        event.preventDefault();
        showQuestion(destination);
        stepButtons[destination].focus();
      }
    });
    stepButtons.push(step);
    tabs.appendChild(step);
    setStepStatus(questionIndex, "");

    const panel = document.createElement("div");
    panel.className = "fcpython-quiz-panel";
    panel.id = panelId;
    panel.setAttribute("role", "tabpanel");
    panel.setAttribute("aria-labelledby", tabId);
    panel.tabIndex = -1;

    const fieldset = document.createElement("fieldset");
    fieldset.className = "fcpython-quiz-question";

    const legend = document.createElement("legend");
    legend.textContent = question.prompt;
    fieldset.appendChild(legend);

    question.options.forEach((option, optionIndex) => {
      const label = document.createElement("label");
      label.className = "fcpython-quiz-option";

      const input = document.createElement("input");
      input.type = "radio";
      input.name = `${quiz.id}-${question.id}`;
      input.value = String(optionIndex);
      input.addEventListener("change", () => {
        setStepStatus(questionIndex, "answered");
        feedbackNodes[questionIndex].textContent = "";
        feedbackNodes[questionIndex].className = "fcpython-quiz-feedback";
        score.textContent = "";
        showQuestion(questionIndex);
      });

      const text = document.createElement("span");
      text.textContent = option;

      label.appendChild(input);
      label.appendChild(text);
      fieldset.appendChild(label);
    });

    const feedback = document.createElement("p");
    feedback.className = "fcpython-quiz-feedback";
    feedback.setAttribute("aria-live", "polite");
    feedbackNodes.push(feedback);
    fieldset.appendChild(feedback);
    panel.appendChild(fieldset);
    questionPanels.push(panel);
    questions.appendChild(panel);
  });

  container.appendChild(questions);

  const actions = document.createElement("div");
  actions.className = "fcpython-quiz-actions";

  const previous = document.createElement("button");
  previous.type = "button";
  previous.className = "fcpython-quiz-secondary";
  previous.textContent = "Previous";
  previous.addEventListener("click", () => {
    showQuestion(currentQuestion - 1, true);
  });

  const next = document.createElement("button");
  next.type = "button";
  next.textContent = "Next question";
  next.addEventListener("click", () => {
    showQuestion(currentQuestion + 1, true);
  });

  const check = document.createElement("button");
  check.type = "button";
  check.textContent = "Check answers";

  const reset = document.createElement("button");
  reset.type = "button";
  reset.className = "fcpython-quiz-secondary fcpython-quiz-reset";
  reset.textContent = "Reset";

  const score = document.createElement("p");
  score.className = "fcpython-quiz-score";
  score.setAttribute("aria-live", "polite");

  check.addEventListener("click", () => {
    let correctCount = 0;
    let firstQuestionToReview = null;

    quiz.questions.forEach((question, questionIndex) => {
      const selected = container.querySelector(
        `input[name="${quiz.id}-${question.id}"]:checked`
      );
      const feedback = feedbackNodes[questionIndex];

      if (!selected) {
        feedback.textContent = "Choose an answer before checking.";
        feedback.className = "fcpython-quiz-feedback";
        setStepStatus(questionIndex, "unanswered");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
        return;
      }

      const selectedIndex = Number(selected.value);
      if (selectedIndex === question.answer_index) {
        correctCount += 1;
        feedback.textContent = `✅ Correct. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-correct";
        setStepStatus(questionIndex, "correct");
      } else {
        const answer = question.options[question.answer_index];
        feedback.textContent = `❌ Not yet. Correct answer: ${answer}. ${question.explanation}`;
        feedback.className = "fcpython-quiz-feedback is-incorrect";
        setStepStatus(questionIndex, "incorrect");
        if (firstQuestionToReview === null) {
          firstQuestionToReview = questionIndex;
        }
      }
    });

    score.textContent = `Score: ${correctCount}/${quiz.questions.length}`;
    if (firstQuestionToReview !== null) {
      showQuestion(firstQuestionToReview, true);
    }
  });

  reset.addEventListener("click", () => {
    container.querySelectorAll("input[type='radio']").forEach((input) => {
      input.checked = false;
    });
    feedbackNodes.forEach((feedback) => {
      feedback.textContent = "";
      feedback.className = "fcpython-quiz-feedback";
    });
    stepButtons.forEach((_, questionIndex) => {
      setStepStatus(questionIndex, "");
    });
    score.textContent = "";
    showQuestion(0, true);
  });

  actions.appendChild(previous);
  actions.appendChild(next);
  actions.appendChild(check);
  actions.appendChild(reset);
  container.appendChild(actions);
  container.appendChild(score);
  showQuestion(0);
  return container;
}

6. Read failures from the owning layer

Invalid YAML

ERROR: YAMLException: bad indentation of a mapping entry
  at docs/_quarto.yml:9:7

Open the named file and line. Compare indentation with parent keys. Do not edit a QMD paragraph or generated HTML for a configuration parse error.

A common defect is:

website:
  sidebar:
  contents:
    - index.qmd

contents must be nested beneath sidebar:

website:
  sidebar:
    contents:
      - index.qmd

Missing source target

Unable to resolve link target: reference/api.qmd

Start from the source page containing the link. Resolve reference/api.qmd relative to that page. Check whether the link depth is wrong, the file moved, or navigation still names a retired route.

Page parses but a diagram fails

A Mermaid error belongs to the diagram source. Keep labels simple, quote punctuation-sensitive labels, and preserve the required execution options. Run the focused Mermaid parser and render again rather than replacing the diagram with an unverified screenshot.

Render succeeds but a page is missing

Inspect project render targets and sidebar paths. A page excluded by project configuration will not reappear because its old HTML remains in an uncleared _site. This is why a clean output directory matters: stale files can conceal a missing render target.

7. Compare toolchains without maintaining three sites

Quarto is the complete path here because this course already uses QMD, code examples, diagrams, and a Quarto website. Other projects may choose differently:

• Sphinx has a mature Python domain and autodoc ecosystem for API-heavy libraries, often using reStructuredText or MyST.
• MkDocs emphasizes Markdown-oriented documentation websites and a plugin ecosystem.
• Quarto supports technical documents, executable content, cross-references, websites, books, and multiple output formats.

Choose from reader and maintainer needs: API generation, markup familiarity, execution model, extension ecosystem, output formats, accessibility, and team capacity. Do not build three versions before the project has one trustworthy site.

8. Lab: assemble the Midnight Museum site

Create the five-page source tree and _quarto.yml from this lesson. Your site must provide:

• index.qmd with value, prerequisites, and direct tutorial link;
• tutorial.qmd with the verified Moon Dial result;
• how-to-rank-exhibits.qmd for changing one input;
• why-ranking-is-deterministic.qmd explaining explicit inputs and no hidden state;
• api.qmd describing the public signature, result, and failures;
• reader-focused sidebar text and page navigation;
• one figure or table with a stable cross-reference;
• descriptive internal QMD links;
• repository feedback actions only if a real URL is supplied.

Run:

quarto render docs

Verify:

from pathlib import Path

site = Path("docs/_site")
expected = {
    "index.html",
    "tutorial.html",
    "how-to-rank-exhibits.html",
    "why-ranking-is-deterministic.html",
    "api.html",
}
assert expected <= {path.name for path in site.glob("*.html")}

Then introduce and repair:

1. one incorrectly indented contents key;
2. one link to reference/api.qmd that should target api.qmd;
3. one cross-reference whose ID differs by an underscore;
4. one page removed from navigation while stale HTML remains.

Clear generated output before verifying the final repair so a stale file cannot produce a false pass.

Hint: build one navigable page before adding features

Start with index.qmd, tutorial.qmd, and a two-item sidebar. Render. Add one page and link at a time, rerendering after each structural change.

Reveal a complete minimal configuration

project:
  type: website
  output-dir: _site

website:
  title: Midnight Museum Quest
  page-navigation: true
  search: true
  sidebar:
    style: floating
    contents:
      - href: index.qmd
        text: Start Here
      - href: tutorial.qmd
        text: Guided Museum Visit
      - href: how-to-rank-exhibits.qmd
        text: Change a Ranking
      - href: why-ranking-is-deterministic.qmd
        text: Why Rankings Repeat
      - href: api.qmd
        text: Public API

format:
  html:
    toc: true

The content of each page still owns reader quality. This configuration only makes the intended source set and order explicit.

Key points

• Keep QMD, configuration, and assets as source; treat _site as replaceable output.
• Design navigation around reader movement rather than filename order.
• Link to source QMD paths so Quarto can resolve the chosen output format.
• Use callouts and cross-references only when their structure helps the reader.
• Preview accelerates local iteration; a clean complete render owns the deployment artifact.
• Diagnose YAML, source-link, diagram, and stale-output failures at their owning layer.
• Teach and maintain one suitable toolchain completely before comparing alternatives.

References

• Creating a Quarto website
• Quarto website navigation
• Quarto cross-references
• Quarto callout blocks
• Sphinx documentation
• MkDocs documentation

Next: Publish Documentation and Keep It Trustworthy