docs: stop styling page references as blockquotes - #2666
Merged
tonyandrewmeyer merged 6 commits intoAug 20, 2026
Merged
Conversation
…outs Un-blockquote 'See more:', 'See also:', 'See first:', and 'Read more:' callouts across docs/howto, docs/explanation, and one tutorial page. References to other pages aren't quotes, so shouldn't be styled as quotes (per canonical/charmlibs#493).
charmlibs#493, which the issue cites, sets the rule: two items comma separated, three or more bulleted. Eight converted lines had three or more items but stayed on one line, including a five-item ops.ActionEvent list. Also converts the eight "> Examples:" blockquotes, which are references to charm source styled as quotes for the same historical reason. The tutorial's breadcrumb and "See previous"/"See next" blockquotes are navigation rather than references, and are left alone.
Vale skips blockquote contents, so unquoting these lines is what exposed "Charmlibs" and "timeframes" -- both were already in the docs. "Charmlibs" is a product name, so it goes in the custom wordlist alongside Jubilant's and Borescope. "timeframes" is reworded to "time frames", which is the form the US spellcheck accepts.
james-garner-canonical
approved these changes
Aug 17, 2026
james-garner-canonical
left a comment
james-garner-canonical
left a comment
Contributor
There was a problem hiding this comment.
This looks good to me.
dwilding
approved these changes
Aug 18, 2026
dwilding
left a comment
dwilding
left a comment
Contributor
There was a problem hiding this comment.
Thanks for doing this!
Elsewhere we've discussed adopting this style: If there are 2 links, write them inline. If there are 3+ links, use bullets.
I asked my agent to scan the docs and it found 13 instances to change.
Files with an instance of 2 bullets:
docs/explanation/security.mddocs/howto/debug-your-charm.mddocs/howto/make-your-charm-discoverable.mddocs/howto/manage-interfaces.mddocs/howto/write-integration-tests-for-a-charm.mddocs/howto/write-unit-tests-for-a-charm.md
Files with an instance of 1 bullet:
docs/howto/manage-charms.mddocs/howto/write-integration-tests-for-a-charm.md
I think it's worth changing these instances to inline style. I'd be OK if you do that on this PR. Or I'd be happy to open a separate PR.
Review feedback: the Juju cross-reference still read "Juju support timeframes", while the Ops one had been reworded to "time frames" to get past the US spellcheck. "Support commitments" describes both better and is spelled the same way everywhere. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The same rule that bulleted the three-or-more-item lists puts one and two items back on a single comma-separated line, which is what the rest of the docs already do. Eleven blocks across six files. Two are left as bullets: the lists in debug-your-charm.md and manage-interfaces.md carry a descriptive clause on each item, so joining them with commas would run those clauses together. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ckquotes-for-links # Conflicts: # docs/explanation/versions.md
Collaborator
Author
Done in this one. |
Collaborator
Author
|
@dwilding do you want to look over the new changes? |
dwilding
approved these changes
Aug 20, 2026
dwilding
left a comment
dwilding
left a comment
Contributor
There was a problem hiding this comment.
Changes look good. I agree with leaving a couple of 2-bullet blocks because the bullets have longer explanations.
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
3 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.
Replaces the
> See also:/> See more:/> See first:blockquotes throughoutdocs/with plain body text.Also converts the eight
> Examples:blocks, which point at charm source and are quote-styled for the same historical reason.Two related things left alone, each worth a separate decision:
> **See previous:**/> **See next:**blockquotes. Those are navigation rather than references, and the tutorial is being worked on separately at the moment.> Added in ops 2.15/> Added in ops 2.17version notes inmanage-pebble-health-checks.md.Fixes #2643