Skip to content

feat: reserve "key" field in page configuration for stable slide referencing - #527

Merged
k1LoW merged 3 commits into
mainfrom
key
Jun 1, 2026
Merged

k1LoW merged 3 commits into
mainfrom
key

Conversation

@k1LoW

@k1LoW k1LoW commented May 27, 2026

Copy link
Copy Markdown
Owner

Refs: #523

This pull request reserves key as 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:

  • key is optional and opaque; deck does not interpret its content, length, or character set.
  • It has no effect on rendering and is not considered for content equality (changing only the key does not trigger a slide update).
  • Empty values are treated as unset.
  • Uniqueness is enforced at parse time. Two pages declaring the same non-empty key cause Parse to return duplicate 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:

<!-- {"key": "a7b5", "layout": "title-and-body"} -->

# Slide title

---

<!-- {"key": "c9d2"} -->

# Another slide

Changes:

  • Add Key field to md.Config and md.Content, and copy it through when parsing the page-config HTML comment.
  • Add validateKeys and call it from md.Parse after defaults are reflected.
  • Update README.md (page configuration section and the agent-facing guide) to document key.
  • Add testdata/key.md (+ golden) to TestParse and a new TestValidateKeys covering: no keys, all unique, mixed keyed/unkeyed, empty-key collisions (not duplicates), and a duplicate-key error.

Verified with go build ./... and go test ./... (all packages pass).

…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
@k1LoW k1LoW self-assigned this May 29, 2026
@k1LoW k1LoW added enhancement New feature or request tagpr:minor labels May 29, 2026
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.
@github-actions

This comment has been minimized.

Split the bullet into separate sentences instead of joining clauses
with an em dash.
@github-actions

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (f9697fd) #527 (33f246c) +/-
Coverage 33.7% 33.9% +0.2%
Code to Test Ratio 1:0.9 1:0.9 +0.0
Test Execution Time 12s 11s -1s
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%)

Files Coverage +/- Status
md/md.go 79.7% +0.4% modified

Reported by octocov

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Key to Markdown page config/content parsing and validates non-empty keys are unique across pages.
  • Documents key in 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
k1LoW marked this pull request as ready for review June 1, 2026 01:07
@k1LoW
k1LoW merged commit 3f1fd76 into main Jun 1, 2026
2 checks passed
@k1LoW
k1LoW deleted the key branch June 1, 2026 13:35
@github-actions github-actions Bot mentioned this pull request Jun 1, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request tagpr:minor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址