From 17487342c232984af390cf5bfa0016654279558c Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Fri, 24 Apr 2026 05:45:45 -0700
Subject: [PATCH] docs: clarify vocabulary page generation pipeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrites the Development section's vocab paragraph to describe the
actual two-stage build:

1. TTL → markdown via the `vocab` CLI from isamplesorg/vocab_tools
   (installed via pipx in CI), driven by scripts/generate_vocab_docs.sh
2. markdown → HTML via `quarto render` applying _quarto.yml's theme,
   nav, and sidebar

Also notes that scripts/vocab2md.py is no longer invoked (PR #48
switched to the `vocab markdown` CLI entry point — same tool, same
transform) to prevent future confusion about which code produces
the rendered vocabulary pages.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b4f0b6b..1bfee90 100644
--- a/README.md
+++ b/README.md
@@ -40,13 +40,23 @@ Preview the site:
 quarto preview
 ```
 
-Vocabulary documentation is generated from the vocabulary source ttl files using a python script, `scripts/vocab2md.py` and a convenience shell script wrapper, `scripts/generate_vocab_docs.sh`. To regenerate the vocabulary documentation, first `cd` to the root folder of the documentation, then:
+### Vocabulary page generation
+
+The vocabulary pages under `models/generated/vocabularies/` (e.g. [material_sample_object_type.html](https://isamples.org/models/generated/vocabularies/material_sample_object_type.html)) are produced by a deterministic two-stage pipeline:
+
+1. **TTL → markdown.** `scripts/generate_vocab_docs.sh` fetches each `.ttl` from [isamplesorg/vocabularies](https://github.com/isamplesorg/vocabularies) (and the extension repos) and runs `vocab markdown <ttl-url>` — the `vocab` CLI from [isamplesorg/vocab_tools](https://github.com/isamplesorg/vocab_tools), installed via `pipx` in CI. The output is written as a `.qmd` (core vocabularies) or `.md` (extensions) into `models/generated/`.
+2. **Markdown → HTML.** `quarto render` walks the site and applies the theme, navigation, and sidebar defined in `_quarto.yml` to every page, including the generated vocabulary markdown. The site chrome comes from Quarto; the vocabulary content is untouched.
+
+Both stages run in the [`quarto-pages.yml`](.github/workflows/quarto-pages.yml) GitHub Action on every deploy.
+
+To regenerate locally, from the repo root:
 
 ```
 scripts/generate_vocab_docs.sh
+quarto render
 ```
 
-The generated docs are placed under `models/generated/vocabularies`
+**Note on `scripts/vocab2md.py`.** An earlier version of this pipeline invoked `vocab2md.py` directly. PR [#48](https://github.com/isamplesorg/isamplesorg.github.io/pull/48) switched to the `vocab markdown` CLI entry point — same tool, same transform. The `vocab2md.py` file is retained for reference but is no longer part of the build.
 
 After editing, push the sources to GitHub. The rendered pages are generated using the `Render using Quarto and push to GH-pages` GitHub action that is currently manually triggered.