Skip to content

fix: backtick fix rendering under {dropdown}#347

Open
iamsharduld wants to merge 4 commits into
track/2from
cos-lite-microk8s-doc-fixes-hotfix
Open

fix: backtick fix rendering under {dropdown}#347
iamsharduld wants to merge 4 commits into
track/2from
cos-lite-microk8s-doc-fixes-hotfix

Conversation

@iamsharduld
Copy link
Copy Markdown
Contributor

@iamsharduld iamsharduld commented May 15, 2026

Issue

Documentation in cos-lite not rendered properly

Solution

Removed removed backticks

Checklist

  • I have added or updated relevant documentation.
  • PR title makes an appropriate release note and follows conventional commits syntax.
  • Merge target is the correct branch, and relevant tandem backport PRs opened.

@iamsharduld iamsharduld requested review from mmkay and sed-i May 15, 2026 10:33
`snap_microk8s` group.

```{dropdown} Add your user to the `snap_microk8s` group
```{dropdown} Add your user to the snap_microk8s group
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You'll likely need to add the word to the .custom_wordlist.txt

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Comment thread docs/.custom_wordlist.txt Outdated
SHA
SLAs
Snapcraft
snap_microk8s
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This shouldn't be here, as it's not a "word".
The backticks are not spellchecked, and this in fact should be inside backticks.
Odd that single backticks mess up the formatting.
@YanisaHS?

@iamsharduld
Copy link
Copy Markdown
Contributor Author

Root cause: per CommonMark, the info string of a backtick-fenced block can't contain backticks, so the `snap_microk8s` in the {dropdown} title breaks the fence line. @sed-i's instinct that the wordlist is the wrong fix is right, but keeping the inline-code formatting requires a different fence (like ":::"). MyST's colon_fence gives us that: ::: accepts backticks in the title.

Proposed fix:

1. docs/conf.py — enable the extension (line 244):

myst_enable_extensions = {"colon_fence"}

⚠️ Must be a set, not a listcanonical_sphinx calls .update() on it, which fails on lists.

2. cos-lite-microk8s-sandbox.md — switch the fence, keep the backticks:

:::{dropdown} Add your user to the `snap_microk8s` group
  ...
:::

3. Revert the snap_microk8s entry in .custom_wordlist.txt — with backticks restored, it renders inside <code>, which spellingcheck.yaml already ignores.

Verified locally against a canonical_sphinx repro: current track/2 parses the dropdown as literal text; the colon-fence version renders correctly with snap_microk8s formatted as <code> in the summary.

@iamsharduld iamsharduld requested review from mmkay and sed-i May 19, 2026 06:58
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.

3 participants