microsoft / microsoft/hve-core
Dynamically generate Docusaurus collection pages from YAML manifests
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Summary
After PR #1316 (closes #1256) introduced auto-generated `collection.md` files from YAML manifests for GitHub and extension packaging, Docusaurus still maintains **two parallel, hand-coded data sources** that duplicate information already available in the collection YAML manifests. These should be replaced with dynamically generated content sourced from the same YAML manifests.
## Problem
The Docusaurus site has two hand-maintained sources that duplicate collection metadata:
1. **`docs/getting-started/collections.md`** — A manually written table listing all 14 collections with descriptions, per-type artifact counts (Agents, Prompts, Instructions, Skills), maturity levels, and marketplace install links. Also includes a Mermaid dependency diagram.
2. **`docs/docusaurus/src/data/collectionCards.ts`** — 12 hard-coded `CollectionCardDefinition` objects with name, description, maturity, and href fields. The `resolveCollectionCards(counts)` function merges artifact counts from `customFields.collectionCounts` at runtime.
When a collection is added, renamed, or updated, maintainers must update **three separate locations**: the YAML manifest, `collections.md`, and `collectionCards.ts`. This creates drift risk and maintenance overhead.
## Existing Infrastructure
`docusaurus.config.js` already reads collection YAML manifests at build time via `countYamlPaths()` to populate `customFields.collectionCounts`, which feeds artifact count badges on the homepage. This means the YAML-to-Docusaurus pipeline partially exists — it just needs to be extended to cover descriptions, maturity, and page content.
## Proposed Approach
### Phase 1: Replace `collectionCards.ts` hard-coded definitions
- Source card definitions (name, description, maturity, href) from collection YAML manifests at build time via `docusaurus.config.js` custom fields.
- Remove the 12 hard-coded `CollectionCardDefinition` objects from `collectionCards.ts`.
- Keep `resolveCollectionCards()` as a thin adapter that merges the YAML-sourced definitions with counts.
### Phase 2: Auto-generate the `collections.md` page
- Generate `docs/getting-started/collections.md` (or a replacement) from collection YAML manifests and their companion `collection.md` files.
- Preserve the existing table structure (description, artifact counts, maturity, install links) but source all data dynamically.
- Consider whether the Mermaid dependency diagram can also be generated from manifest metadata.
### Phase 3: Add per-collection Docusaurus pages (optional)
- Generate individual Docusaurus pages for each collection, sourced from the auto-generated `collections/*.collection.md` files.
- Add a "Collections" category to `sidebars.js` linking to individual collection pages.
- Update card hrefs to point to individual collection pages instead of the shared overview.
## Files to Modify
| File | Current State | Change |
|---|---|---|
| `docs/docusaurus/src/data/collectionCards.ts` | 12 hard-coded card definitions | Source from YAML manifests via custom fields |
| `docs/getting-started/collections.md` | Hand-maintained table with 14 collections | Auto-generate from YAML manifests |
| `docs/docusaurus/docusaurus.config.js` | Reads YAML for counts only via `countYamlPaths()` | Extend to read descriptions, maturity, install links |
| `docs/docusaurus/sidebars.js` | No collection category | Add collection category (Phase 3) |
| `docs/docusaurus/src/pages/index.tsx` | Renders cards from `resolveCollectionCards()` | No change expected (adapter pattern preserved) |
## Acceptance Criteria
- [ ] Homepage collection cards are sourced from YAML manifests with zero hard-coded definitions
- [ ] The collections overview page content is generated from YAML manifests
- [ ] Adding a new collection requires only updating the YAML manifest (and running generation)
- [ ] `npm run docs:build` succeeds with `onBrokenLinks: 'throw'`
- [ ] No visual regression on the homepage or collections page
## Context
- PR #1316 / Issue #1256: Introduced auto-generated `collection.md` files for GitHub and extension contexts
- The auto-generated files live at `collections/*.collection.md`, which is outside the Docusaurus docs include path
- `docusaurus.config.js` already demonstrates the pattern of reading YAML manifests at build time
Contributor guide
Assessment
This issue has not been assessed yet.