Fix broken vocabulary links by restoring generation from TTL sources

[Copilot]

The /models/ page had broken links to vocabulary documentation that previously lived at isamplesorg.github.io/metadata/vocabularies/. These pages are generated from TTL files but were missing because the generation script was non-functional.

Changes

Updated scripts/generate_vocab_docs.sh

• Switched from unavailable vocab CLI to existing vocab2md.py script
• Applied fix across all vocabulary generation loops (core + extensions)
• Removed dead commented code for cleaner maintenance

Updated models/index.qmd links

-[Materials Vocabulary](https://isamplesorg.github.io/metadata/vocabularies/materialtype.html)
+[Materials Vocabulary](generated/vocabularies/material_type.html)

Build-time generation (not committed)

• Added models/generated/ patterns to .gitignore to exclude generated files
• Vocabularies are now generated at build time by the existing GitHub Actions workflow
• Kept readme.md files in generated directories for documentation

The vocabularies are now co-located with the main site and generated fresh from canonical TTL sources at build time, preventing repository bloat and ensuring documentation stays in sync with source files. The GitHub Actions workflow already runs scripts/generate_vocab_docs.sh before quarto render (line 58 of .github/workflows/quarto-pages.yml).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>broken links on https://isamples.org/models/</issue_title>
<issue_description>eg,
broken links:
https://isamples.org/metadata/vocabularies/specimentype.html
https://isamples.org/metadata/vocabularies/materialtype.html
https://isamples.org/metadata/vocabularies/sampledfeature.html

what happened to those old pages?</issue_description>

<agent_instructions>Identify reasons for broken link -- presumably there should be new pages that replaced the old ones</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes broken links on https://isamples.org/models/ #45

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This pull request fixes broken vocabulary documentation links on the /models/ page by restoring the generation of vocabulary documentation from TTL (Turtle) source files. The previous documentation was hosted at isamplesorg.github.io/metadata/vocabularies/ but was missing because the generation script was non-functional.

Key Changes:

• Updated the generation script to use the working vocab2md.py Python script instead of the unavailable vocab CLI tool
• Generated 10 vocabulary documentation files (3 core + 7 extensions) from canonical TTL sources
• Updated links in models/index.qmd to point to the newly generated local documentation

Reviewed changes

Copilot reviewed 2 out of 12 changed files in this pull request and generated no comments.

File	Description
scripts/generate_vocab_docs.sh	Switched from vocab CLI to vocab2md.py script for all vocabulary generation loops
models/index.qmd	Updated three broken external links to point to locally generated vocabulary files
models/generated/vocabularies/*.qmd	Generated 3 core vocabulary documentation files from TTL sources
models/generated/extensions/*.md	Generated 7 extension vocabulary documentation files from TTL sources

All generated files include appropriate warnings that they are auto-generated and should not be edited manually. The changes successfully restore the vocabulary documentation that was previously inaccessible.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rdhyee]

Review: Approve with Suggestions

✅ What's Good

• Fixes real broken links - the old external URLs no longer exist
• Uses existing tooling - vocab2md.py was already in scripts, just commented out
• Proper separation - generated files in models/generated/ directory
• Complete coverage - all 10 vocabularies (3 core + 7 extensions) regenerated

💡 Suggestions for Future Cleanup

1. Generated content committed: Consider generating docs at build time (CI/pre-render) rather than committing 6K+ lines of generated files. Could add models/generated/ to .gitignore.

2. Comment clutter in script: The dead vocab markdown lines could be removed entirely since that CLI is unavailable:

   # Just delete these commented lines:
   #    vocab markdown "${SOURCE_BASE}${src}" > "${DEST_FOLDER}${fname}"

These are minor cleanups - the fix itself is correct and needed. Approving!

🤖 Review by Claude Code

[rdhyee]

Review Update: Request Changes

After further analysis (with Codex confirmation), requesting changes before merge.

Required Changes

1. Generate at build time, not commit time

Don't commit the generated files. Instead:

• Add models/generated/ to .gitignore
• Run scripts/generate_vocab_docs.sh in the Quarto pre-render or GitHub Actions workflow
• Update .github/workflows/ to call the script before quarto render

Example workflow addition:

- name: Generate vocabulary documentation
  run: ./scripts/generate_vocab_docs.sh

- name: Render Quarto site
  run: quarto render

2. Clean up the script

Remove the dead vocab CLI lines entirely:

# DELETE these commented lines (the vocab CLI is unavailable):
#    vocab markdown "${SOURCE_BASE}${src}" > "${DEST_FOLDER}${fname}"

Just keep the working Python version.

3. Remove generated files from PR

The 10 generated .md and .qmd files should not be committed:

• models/generated/vocabularies/*.qmd
• models/generated/extensions/*.md

Why This Matters

• Repo bloat: 6,400 lines of generated content shouldn't live in git
• Drift risk: Generated files get stale if TTL sources change
• Best practice: Generate artifacts at build time, not commit time

What to Keep

✅ The link updates in models/index.qmd are correct
✅ The script fix (Python instead of vocab CLI) is correct

---

🤖 Review updated by Claude Code (with Codex consultation)

[Copilot]

Review Update: Request Changes

After further analysis (with Codex confirmation), requesting changes before merge....

All requested changes have been implemented in commit 27701f7:

1. ✅ Generated files removed from git - All 10 vocabulary files deleted
2. ✅ Added to .gitignore - models/generated/ patterns added (keeping readme.md files)
3. ✅ Script cleaned up - Removed all dead vocab CLI commented lines

The vocabularies will now be generated at build time by the existing workflow step (line 58 of quarto-pages.yml). Tested locally - script runs successfully and generated files are properly ignored by git.

[rdhyee]

Updated Review: Approve ✅

After checking the workflow, I see quarto-pages.yml already calls generate_vocab_docs.sh before rendering. The generated files will be regenerated at build time regardless.

What's correct:

• ✅ Script fix (vocab2md.py instead of broken vocab CLI)
• ✅ Link updates in models/index.qmd

What's suboptimal but acceptable:

• ⚠️ Generated files committed (redundant - workflow regenerates them)
• ⚠️ Dead commented code in script

These cleanups are tracked in issue #47 and can be done separately. Merging now fixes the broken links.

---

🤖 Claude Code