docs: design for document-type config#52
Closed
mckeea wants to merge 1 commit into
Closed
Conversation
Proposal for handling non-standard documents (the CDSE migration dashboard) generically: a `document-type` frontmatter field plus a per-type YAML config that declares which elements a type has and which formats it renders. Design only - no pipeline code changed. Mirrors the existing categories.yml + helpers/categories.py pattern. The core mechanism (per-document frontmatter can restrict the rendered format set) is verified both against Quarto's docs and by rendering through the real _meta config. Three open questions are flagged for review, including that .llms.md is produced by `llms-txt: true` rather than the gfm writer, which contradicts CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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
1 participant
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.
What
Design proposal only — no pipeline code changed. Adds one document to
ai/thoughts/plans/.Handles the new
CLMS_CDSE_Migration_Dashboard.qmd(and its sibling..._Status.qmd) generically: adocument-typefrontmatter field + a per-type YAML config declaring which elements a type has and which formats it renders. Mirrors the existingcategories.yml+helpers/categories.pypattern, so a future type is a YAML entry rather than a code change.Per maintainer decisions: declarative on/off toggles (no
drop:-style verbs), thedocumenttype carries the baseline explicitly, dashboards are HTML-only.Why it's a pipeline problem, not an authoring one
strip_unknown_frontmatter.py's allowlist deletestoc/format/cssfrom the build copy, so a document cannot opt out of anything itself. The AI keywords + intro for the dashboard are already generated and get injected at build.Verified
The design rests on per-document frontmatter being able to restrict the format set inside the single project-wide render. Confirmed against Quarto's docs (
formatis the documented exception to metadata merging) and by rendering two fixtures through the real_metaconfig: the one declaringformat: htmlproduced no PDF and no gfm output, and dropped its PDF download link automatically.Open questions flagged for review
.llms.mdcomes fromwebsite: llms-txt: true, not the gfm writer — soformats: [html]does not suppress it. This contradictsCLAUDE.md.code: false(retiring the OJS code-hiding hack) is unverified — my test was inconclusive and is honestly marked as such.default-before-body.htmlneeds handling.🤖 Generated with Claude Code