microsoft / microsoft/hve-core
docs: update collections.md to document H1 heading requirement for collection.md files
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
**Component:** Documentation
**Bug Description**
`docs/customization/collections.md` does not mention that `*.collection.md` files must begin with a top-level H1 heading. This requirement was enforced in commit [`42cc137`](https://github.com/microsoft/hve-core/commit/42cc13775e90f84332846ea47a46045a8ae983d4) (#1372), which removed the markdownlint exclusion for `collections/*.collection.md` and updated all existing collection files to add MD041-compliant H1 headings.
Additionally, `scripts/plugins/Modules/PluginHelpers.psm1` now strips this H1 heading when injecting collection content into plugin READMEs (to avoid duplicate titles). This stripping behavior is undocumented.
**Expected Behavior**
Step 3 in the "Creating a Collection" section of `docs/customization/collections.md` should note:
- The `*.collection.md` file must begin with a top-level H1 heading (enforced by MD041 markdownlint rule).
- The H1 is stripped automatically during plugin generation; it should contain the human-readable collection name.
**Steps to Reproduce**
See PR #1372 (commit `42cc137`), which introduced:
- Enforcement of MD041 on `collections/*.collection.md`
- H1 stripping in `scripts/plugins/Modules/PluginHelpers.psm1`
**Additional Context**
- Documentation file: `docs/customization/collections.md` — "Creating a Collection" section, step 3
- Code file: `scripts/plugins/Modules/PluginHelpers.psm1` — `New-PluginReadmeContent` function
- Code file: `scripts/extension/Prepare-Extension.ps1` — `New-CollectionReadme` function (wraps generated H3 sections under H2 for MD001 compliance)
> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/25725059723/agentic_workflow) · ● 784.3K · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with step 3 in docs/customization/collections.md, then read New-PluginReadmeContent in scripts/plugins/Modules/PluginHelpers.psm1 and New-CollectionReadme in scripts/extension/Prepare-Extension.ps1. Update the documentation to cover the required H1, its collection name, and stripping during generation; verify the file satisfies MD041 and the documented behavior matches these entry points.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, powershell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100