fix: prefer Markdown frontmatter titles - #770
Draft
goxl-wtf wants to merge 1 commit into
Draft
Conversation
Use a non-empty string title from leading YAML frontmatter before the first heading or filename fallback. Keep title output single-line and ignore metadata when falling back to a body heading. Version title extraction in the embedding fingerprint so vector metadata is refreshed. Legacy empty fingerprints remain pending because one matching sample cannot safely validate documents with heterogeneous title semantics. Tests: Node and Bun unit suites, store suites, typecheck, build, diff-check
|
Dear tobi/qmd,
We would like to acknowledge that we have received your request and a ticket has been created.
A support representative will be reviewing your request and will send you a personal response.(usually within 24-48 hours).
Thank you for your patience.
…On Tue, Jul 14 2026, at 08:56 AM, tobi/qmd ***@***.***> wrote:
Summary
* prefer a non-empty string title from leading YAML frontmatter
* keep heading and filename fallbacks, excluding the metadata block from heading detection
* support YAML --- and ... end markers, BOM/CRLF, malformed metadata fallback, and single-line title normalization
* version title extraction in the embedding fingerprint so corrected titles are embedded on the next qmd embed
* keep legacy empty-fingerprint vectors pending instead of bulk-adopting heterogeneous documents from one matching sample
Why this is separate from #551 (#551) #551 combines frontmatter title extraction with frontmatter-as-a-separate-chunk behavior and a new parser dependency. This PR is intentionally title-only: it uses the existing pinned (#551) yaml dependency and does not change chunk content, boundaries, or constants.
A downstream 62-case retrieval evaluation did not support changing frontmatter chunking: the stripped projection changed MRR by -0.0385 with paired p=0.810602. Keeping the concerns separate therefore makes the title correction independently reviewable and avoids bundling an unproven chunking change.
Migration behavior
Existing embeddings have old title semantics. The fingerprint bump marks named legacy vectors pending. Empty pre-fingerprint rows also remain pending because one matching sample cannot prove that documents with different frontmatter titles are current. qmd doctor reports the pending documents and the next qmd embed refreshes them.
Tests
* full Node unit suite
* full Bun unit suite: 890 passed, 42 skipped
* Node and Bun store suites: 232 passed each
* TypeScript typecheck
* production build git diff --check You can view, comment on, or merge this pull request online at: #770 (#770) Commit Summary ab37b3c fix: prefer Markdown frontmatter titles (ab37b3c) File Changes
( 4 files) (https://github.com/tobi/qmd/pull/770/files) M CHANGELOG.md
(7) (https://github.com/tobi/qmd/pull/770/files#diff-06572a96a58dc510037d5efa622f9bec8519bc1beab13c9f251e97e657a9d4ed) M README.md
(2) (https://github.com/tobi/qmd/pull/770/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5) M src/store.ts
(53) (https://github.com/tobi/qmd/pull/770/files#diff-2717c7fb31c2070dd96f07394997809bc9be7f3fff03ab638db696cc480f39b6) M test/store.test.ts
(247) (https://github.com/tobi/qmd/pull/770/files#diff-ecc9e7b9a74de1ebac3cd3038ffc91cd42684ca2890738d3b93139c723c36407) Patch Links: https://github.com/tobi/qmd/pull/770.patch (https://github.com/tobi/qmd/pull/770.patch) https://github.com/tobi/qmd/pull/770.diff (https://github.com/tobi/qmd/pull/770.diff)
—
Reply to this email directly, view it on GitHub, or (#770?email_source=notifications&email_token=BRF3HGZKHHIXYFD3AU4ILMT5EXYUFA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF42DANJRGA2DIMJRGSTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVRTG633UMVZF6Y3MNFRWW) unsubscribe. (https://github.com/notifications/unsubscribe-auth/BRF3HG3ZFDPR5T2BTWLZMZD5EXYUFAVCNFSNUABGKJSXA33TNF2G64TZHMYTCMJSGM3DKMZQGE5US43TOVSTWNBYHAYTINZUGU2TLILWAI)
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and (https://github.com/notifications/mobile/ios/BRF3HG5PLZMMXEK62LKEOHD5EXYUFA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF42DANJRGA2DIMJRGSTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVJTG633UMVZF62LPOM) Android. Download it today! (https://github.com/notifications/mobile/android/BRF3HGZELJ6UTSHWJ6JNDG35EXYUFA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF42DANJRGA2DIMJRGSTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVZTG633UMVZF6YLOMRZG62LE)
You are receiving this because you are subscribed to this thread. Message ID: <tobi/qmd/pull/770 @ github . com> [
{
***@***.***": "http://schema.org",
***@***.***": "EmailMessage",
"potentialAction": {
***@***.***": "ViewAction",
"target": "#770?email_source=notifications\u0026email_token=BRF3HG52LFIA2DM2WXM64R35EXYUFA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF42DANJRGA2DIMJRGSTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVNTW2YLJNRPWG3DJMNVQ",
"url": "#770?email_source=notifications\u0026email_token=BRF3HG52LFIA2DM2WXM64R35EXYUFA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF42DANJRGA2DIMJRGSTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVNTW2YLJNRPWG3DJMNVQ",
"name": "View Pull Request"
},
"description": "View this Pull Request on GitHub",
"publisher": {
***@***.***": "Organization",
"name": "GitHub",
"url": "https://github.com"
}
}
]
|
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
2 participants
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.
Summary
titlefrom leading YAML frontmatter---and...end markers, BOM/CRLF, malformed metadata fallback, and single-line title normalizationqmd embedWhy this is separate from #551
#551 combines frontmatter title extraction with frontmatter-as-a-separate-chunk behavior and a new parser dependency. This PR is intentionally title-only: it uses the existing pinned
yamldependency and does not change chunk content, boundaries, or constants.A downstream 62-case retrieval evaluation did not support changing frontmatter chunking: the stripped projection changed MRR by -0.0385 with paired p=0.810602. Keeping the concerns separate therefore makes the title correction independently reviewable and avoids bundling an unproven chunking change.
Migration behavior
Existing embeddings have old title semantics. The fingerprint bump marks named legacy vectors pending. Empty pre-fingerprint rows also remain pending because one matching sample cannot prove that documents with different frontmatter titles are current.
qmd doctorreports the pending documents and the nextqmd embedrefreshes them.Tests
git diff --check