Repository navigation
Conversation
…rencing
When editing a deck with an AI agent or external tooling, there has been
no stable way to refer to a specific slide across turns: deictic references
("this slide") don't survive turns, page numbers shift on every insert or
delete, and titles or body fragments are rarely unique.
Reserve "key" as a well-known optional field in the per-page JSON config
to give downstream tooling a stable, opaque identifier for each slide.
- Optional, opaque string with no rendering effect (treated similarly to
"freeze" / "skip" / "ignore" in that it never appears in the rendered
output).
- Empty values are treated as unset.
- Uniqueness is enforced at parse time so that consumers can rely on the
identity guarantee instead of treating it as convention.
Refs: #523
golangci-lint funcorder requires unexported methods to come after the struct's exported methods. The unexported validateKeys sat between Parse and ToSlides, which tripped the linter on CI.
This comment has been minimized.
This comment has been minimized.
Split the bullet into separate sentences instead of joining clauses with an em dash.
Contributor
Code Metrics Report
Details | | main (f9697fd) | #527 (33f246c) | +/- |
|---------------------|----------------|----------------|-------|
+ | Coverage | 33.7% | 33.9% | +0.2% |
| Files | 31 | 31 | 0 |
| Lines | 3405 | 3416 | +11 |
+ | Covered | 1150 | 1161 | +11 |
+ | Code to Test Ratio | 1:0.9 | 1:0.9 | +0.0 |
| Code | 7018 | 7037 | +19 |
+ | Test | 6578 | 6616 | +38 |
+ | Test Execution Time | 12s | 11s | -1s |Code coverage of files in pull request scope (79.2% → 79.7%)
Reported by octocov |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reserves key as an optional per-page Markdown configuration field for stable slide references, primarily for AI agents and external tooling, while keeping it out of rendering and content-diff behavior.
Changes:
- Adds
Keyto Markdown page config/content parsing and validates non-empty keys are unique across pages. - Documents
keyin the README page configuration and agent guide sections. - Adds parse golden coverage and validation tests for unique, empty, mixed, and duplicate keys.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
md/md.go |
Adds key parsing, stores it on content, and validates duplicate non-empty keys during parse. |
md/md_test.go |
Adds key.md to parse golden tests and covers duplicate-key validation cases. |
testdata/key.md |
Adds sample Markdown pages with keys. |
testdata/key.md.golden |
Adds expected parsed JSON output including keys. |
README.md |
Documents the new key page configuration field and agent-facing usage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
k1LoW
marked this pull request as ready for review
June 1, 2026 01:07
Merged
social4hyq
pushed a commit
to social4hyq/homebrew-core
that referenced
this pull request
Sep 20, 2026
deck 1.24.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre><!-- Release notes generated using configuration in .github/release.yml at 7d1e45da428a62b61fe637a1f94615a9a55c9e90 --> ## What's Changed ### New Features 🎉 * feat: reserve "key" field in page configuration for stable slide referencing by @k1LoW in k1LoW/deck#527 ### Other Changes * chore(deps): bump the dependencies group with 4 updates by @dependabot[bot] in k1LoW/deck#507 * chore(deps): bump the dependencies group with 4 updates by @dependabot[bot] in k1LoW/deck#509 * chore(deps): bump google.golang.org/api from 0.273.0 to 0.274.0 in the dependencies group by @dependabot[bot] in k1LoW/deck#510 * chore(deps): bump the dependencies group with 2 updates by @dependabot[bot] in k1LoW/deck#511 * chore(deps): bump the dependencies group with 2 updates by @dependabot[bot] in k1LoW/deck#512 * chore(deps): bump the dependencies group with 3 updates by @dependabot[bot] in k1LoW/deck#513 * chore(deps): bump the dependencies group across 1 directory with 2 updates by @dependabot[bot] in k1LoW/deck#518 * chore(deps): bump the dependencies group across 1 directory with 4 updates by @dependabot[bot] in k1LoW/deck#519 * chore(deps): bump the dependencies group with 3 updates by @dependabot[bot] in k1LoW/deck#520 * chore(deps): bump the dependencies group with 3 updates by @dependabot[bot] in k1LoW/deck#521 * fix: resolve govet inline and modernize lint errors by @k1LoW in k1LoW/deck#524 * chore(deps): bump the dependencies group with 2 updates by @dependabot[bot] in k1LoW/deck#522 * chore(deps): bump the dependencies group across 1 directory with 3 updates by @dependabot[bot] in k1LoW/deck#528 * chore(deps): bump goreleaser/goreleaser-action from 7.2.1 to 7.2.2 in the dependencies group by @dependabot[bot] in k1LoW/deck#525 **Full Changelog**: https://github.com/k1LoW/deck/compare/v1.23.1...v1.24.0</pre> <p>View the full release notes at <a href="https://github.com/k1LoW/deck/releases/tag/v1.24.0">https://github.com/k1LoW/deck/releases/tag/v1.24.0</a>.</p> </details> <hr> See merge request: Harmonybrew/homebrew-core!9957
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs: #523
This pull request reserves
keyas a well-known optional field in the per-page JSON configuration comment, so that AI agents and external tooling can refer to a specific slide by a stable, opaque identifier instead of relying on page numbers, headings, or body fragments — all of which shift or collide in practice.Behavior:
keyis optional and opaque; deck does not interpret its content, length, or character set.keydoes not trigger a slide update).keycauseParseto returnduplicate page key %q at pages %d and %d, so downstream consumers can rely on the identity guarantee rather than treating it as a convention.Example:
Changes:
Keyfield tomd.Configandmd.Content, and copy it through when parsing the page-config HTML comment.validateKeysand call it frommd.Parseafter defaults are reflected.README.md(page configuration section and the agent-facing guide) to documentkey.testdata/key.md(+ golden) toTestParseand a newTestValidateKeyscovering: no keys, all unique, mixed keyed/unkeyed, empty-key collisions (not duplicates), and a duplicate-key error.Verified with
go build ./...andgo test ./...(all packages pass).