Repository navigation
[plan] Quick Start: Define 'frontmatter' inline and promote .lock.yml explanation to a callout #43075
Description
Objective
Add a beginner-friendly inline definition of "frontmatter" and make the .lock.yml explanation visually prominent in the Quick Start guide.
Context
From the Documentation Noob Tester report in discussion #42905:
- Issue 3: The word "frontmatter" appears in Step 4 (Customize) with only an inline link but no explanation. Beginners with no YAML background don't know what it means.
- Issue 4: The critical explanation of
.lock.ymlis buried in a plain paragraph and easily skipped by skimmers.
Implementation Plan
Changes
1. Define "frontmatter" inline (Step 4)
In Step 4 (Customize), after the first mention of "frontmatter", add a parenthetical:
"(the
---block at the top of the file that controls when and how the workflow runs)"
Keep the existing link to the Reference page.
2. Promote .lock.yml explanation to a callout
Wrap the current plain-paragraph explanation of .lock.yml in a [!NOTE] callout:
> [!NOTE]
> The `.lock.yml` is the compiled GitHub Actions workflow generated from your markdown — it is what actually runs, and it is regenerated automatically, so you never edit it by hand.Consider also adding a "What just happened?" sub-section after Step 2 that names both new files (.md source and .lock.yml compiled output).
Files to Modify
docs/src/content/docs/quick-start.mdx(or equivalent Quick Start source file in the docs directory)
Acceptance Criteria
- "frontmatter" has an inline parenthetical explanation on first use in Step 4
- The
.lock.ymlexplanation is wrapped in a[!NOTE](or equivalent) callout so it is visually distinct - No existing content is removed — only formatting/presentation is changed
Generated by 📋 Plan Command · 21 AIC · ⌖ 6.73 AIC · ⊞ 4.9K · ◷
Comment /plan to run again
- expires on Jul 4, 2026, 7:12 PM UTC-08:00
Activity