microsoft / microsoft/hve-core

docs: update collections.md to document H1 heading requirement for collection.md files

Open Beginner friendly
#1,584 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation needs-triage
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.