microsoft / microsoft/hve-core

Dynamically generate Docusaurus collection pages from YAML manifests

Open
#1,317 0 comments 0 reactions 1 assignee Claimed by @WilliamBerryiii View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.