Suggested by @cscheid in #6858 (comment):
Having a schema to document and details "text" specification (and other fields) everywhere from one single file could be a nice future enhancement.
The same fields (text, href, icon, rel, target) appear in several schema definitions with overlapping but independently-maintained descriptions:
|
- id: navigation-item-object |
|
object: |
|
closed: true |
|
properties: |
|
aria-label: |
|
string: |
|
description: "Accessible label for the item." |
|
file: |
|
hidden: true |
|
string: |
|
description: | |
|
Alias for href |
|
href: |
|
string: |
|
description: | |
|
Link to file contained with the project or external URL |
|
icon: |
|
string: |
|
description: |
|
short: Name of bootstrap icon (e.g. `github`, `bluesky`, `share`) |
|
long: | |
|
Name of bootstrap icon (e.g. `github`, `bluesky`, `share`) |
|
See <https://icons.getbootstrap.com/> for a list of available icons |
|
id: |
|
# "core identification" |
|
# this field is only used in typescript |
|
schema: string |
|
hidden: true |
|
menu: |
|
arrayOf: |
|
schema: |
|
ref: navigation-item |
|
text: |
|
string: |
|
description: | |
|
Text to display for item (defaults to the |
|
document title if not provided) |
|
url: |
|
hidden: true |
|
string: |
|
description: | |
|
Alias for href |
|
rel: |
|
string: |
|
description: | |
|
Value for rel attribute. Multiple space-separated values are permitted. |
|
See <https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel> |
|
for a details. |
|
target: |
|
string: |
|
description: | |
|
Value for target attribute. |
|
See <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target> |
|
for details. |
|
|
|
- id: giscus-themes |
|
enum: |
|
values: |
|
[ |
|
light, |
|
light_high_contrast, |
|
light_protanopia, |
|
light_tritanopia, |
|
dark, |
|
dark_high_contrast, |
|
dark_protanopia, |
|
dark_tritanopia, |
|
- id: other-links |
|
arrayOf: |
|
object: |
|
properties: |
|
text: |
|
string: |
|
description: "The text for the link." |
|
href: |
|
string: |
|
description: "The href for the link." |
|
icon: |
|
string: |
|
description: "The bootstrap icon name for the link." |
|
rel: |
|
string: |
|
description: "The rel attribute value for the link." |
|
target: |
|
string: |
|
description: "The target attribute value for the link." |
|
required: [text, href] |
|
- id: code-links-schema |
|
schema: |
|
anyOf: |
|
- boolean |
|
- maybeArrayOf: |
|
anyOf: |
|
- object: |
|
properties: |
|
icon: |
|
string: |
|
description: The bootstrap icon for this code link. |
|
text: |
|
string: |
|
description: The text for this code link. |
|
href: |
|
string: |
|
description: The href for this code link. |
|
rel: |
|
string: |
|
description: The rel used in the `a` tag for this code link. |
|
target: |
|
string: |
|
description: The target used in the `a` tag for this code link. |
|
- enum: ["repo", "binder", "devcontainer"] |
Drift between these is real. Documenting markdown support on navigation-item.text (#6858) did not propagate to other-links.text or code-links.text, even though all three describe similar link-target text. Same risk for href, icon, rel, target.
We could extract these into reusable schema fragments and reference them from each site, so a single edit updates every place a field is documented.
Opening this to track the idea.
Suggested by @cscheid in #6858 (comment):
The same fields (
text,href,icon,rel,target) appear in several schema definitions with overlapping but independently-maintained descriptions:quarto-cli/src/resources/schema/definitions.yml
Lines 112 to 178 in 57705c3
quarto-cli/src/resources/schema/definitions.yml
Lines 1321 to 1340 in 57705c3
quarto-cli/src/resources/schema/definitions.yml
Lines 2493 to 2516 in 57705c3
Drift between these is real. Documenting markdown support on
navigation-item.text(#6858) did not propagate toother-links.textorcode-links.text, even though all three describe similar link-target text. Same risk forhref,icon,rel,target.We could extract these into reusable schema fragments and reference them from each site, so a single edit updates every place a field is documented.
Opening this to track the idea.