Skip to content

Conversation

@roberth
Copy link

@roberth roberth commented Oct 17, 2025

Hey all,

Here's a little quality of life improvement that I would like to use for the schema documentation in Nix. (wip)
Thank you for considering!

Cheers, Robert


Add read more links to the properties table in the md format when it has both title and description.

When a schema property has both a title and description, the table now displays the title with a "(read more)" link to the detailed section. This keeps tables compact and scannable while highlighting the existence of the full documentation.

That would otherwise be easy to miss, especially when embedded in documentation where links in definition lists are merely anchors and readers are used to ignoring those.

Changes:

  • Add (read more) in md_template.py
  • Add "middleName" to basic.json example to showcase and test a property with a title and no description. The other combinators were already covered.

To be specific the behavior for all four combinations:

- title and description: (changed)     Shows "Title [(read more)](#anchor)"
- title:                 (unchanged)   Shows "Title"   (no link needed)
- description:           (unchanged)   Shows description text
- none:                  (unchanged)   Shows "-" placeholder

Things checked:

  • The other formats do not have tables that serve as a table of contents, so this change does not apply to them.
  • Viewed all four combinations, which render correctly from generated output Examples include: basic.json (all 4 cases), array_advanced.json

... to the properties table when it has both title and description.

When a schema property has both a title and description, the table now
displays the title with a "(read more)" link to the detailed section.
This keeps tables compact and scannable while highlighting the existence
of the full documentation.

That would otherwise be easy to miss, especially when embedded in
documentation where links in definition lists are merely anchors and
readers are used to ignoring those.

Changes:
- Add (read more) in md_template.py
- Add "middleName" to basic.json example to showcase and test a
  property with a title and no description.
  The other combinators were already covered.

To be specific the behavior for all four combinations:
- title and description: (changed) Shows "Title [(read more)](#anchor)"
- title:                 (unchanged) Shows "Title"   (no link needed)
- description:           (unchanged) Shows description text
- none:                  (unchanged) Shows "-" placeholder

Things checked:
- The other formats do not have tables that serve as a table of contents,
  so this change does not apply to them.
- Viewed all four combinations, which render correctly from generated output
  Examples include: basic.json (all 4 cases), array_advanced.json
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant