fix: markdown linting workflow#379
Merged
SecondSkoll merged 4 commits intocanonical:mainfrom Jul 8, 2025
Merged
Conversation
st3v3nmw
force-pushed
the
fix-markdown-linting
branch
2 times, most recently
from
b16b8fd to
ecc9766
Compare
st3v3nmw
force-pushed
the
fix-markdown-linting
branch
3 times, most recently
from
055a153 to
7ff15e4
Compare
artivis
reviewed
Apr 30, 2025
Contributor
|
We ran in this very issue. Looking forward to see that fixed in the starter pack 👍 . |
Collaborator
|
Thanks for the PR! First, I need to double check where we are with validating external actions. Some teams require the use of Canonical developed or standard GH actions without validation. This means I'll need to check to make sure bumping the action version is okay. That said, I have a suggestion stemming from the second issue - not everyone has NPM on their system, and we're trying to minimise the footprint the starter pack has on a user's system (so we'd prefer to not add any system packages if possible - though it's unavoidable in some cases like PDF generation). What is your opinion on using PyMarkdownLint? Do you see any problems if we were to adopt this instead? Actually, in either case - if there's a local Make target for linting we could just extend our own documentation workflows instead of the remote action... |
Co-authored-by: Jeremie Deray <deray.jeremie@gmail.com>
st3v3nmw
force-pushed
the
fix-markdown-linting
branch
3 times, most recently
from
a1425b3 to
10c87f1
Compare
st3v3nmw
force-pushed
the
fix-markdown-linting
branch
from
10c87f1 to
9b0861a
Compare
Member
Author
|
Hi @SecondSkoll, I've switched to |
SecondSkoll
approved these changes
Jul 8, 2025
Collaborator
SecondSkoll
left a comment
SecondSkoll
left a comment
There was a problem hiding this comment.
LGTM. Sorry for the delay on this.
SecondSkoll
added a commit
that referenced
this pull request
Jul 25, 2025
* Simplify vale binary install (#375) * Simplify vale binary install * Use `vale --version` only to trigger binary download & install * Don't direct output to /dev/null to show potential problems * Update version --------- Co-authored-by: Michael Park <michael.park@canonical.com> * Suggest (#376) * Remove impossible warning It's impossible to skip heading levels in reST (it's designed to avoid this as several of its output formats cannot skip levels either, due to recursive section structures). * Correct underline definition reST permits heading underlines to be longer than the corresponding title, which some authors find convenient (i.e. it's fine to just use a full line of "=") https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections * Only use admonitions advised by the style guide The general style guide at https://docs.ubuntu.com/styleguide/en advises under the admonitions section that only the "warning" and "information" admonition callouts are permitted. Given "information" doesn't exist in reST, "note" is probably the next best thing. Changed "caution" to "warning" and removed "tip" and "important". * Add a section on linking to the Ubuntu man-pages * Add note about image output formats Using * as the image extension allows sphinx to pick the "best" image format for the output it's producing. For example, PNG for web, but embedded PS for PDF. * Fix md inclusion example * Apply rkratky's suggestions from code review Co-authored-by: Robert Krátký <robert.kratky@canonical.com> --------- Co-authored-by: Robert Krátký <robert.kratky@canonical.com> * Fix: Update related links header in MyST and RST style guides (#382) * Doc: add instructions for configuring PDF output (#381) * Doc: add instructions for configuring PDF build - explain latex_documents and how to change the Sphinx configurations - introduce methods for overriding LaTeX templates from the extension * fix: spelling * fix: spelling wordlist * use inclusive words * add notes about format of latex_additional_files * fix: spelling check * improve update logic (#386) * run update only when version increases * add changelog entry * Update and rename README.rst to README.md (#387) Changed README format to markdown for correct rendering in the GitHub UI. Updated the Structure section. * Switch the recommendation to Sphinx design tabs (#383) * feat: adds sphinx sitemap support (#389) * docs: update toctree reference * feat: add sitemap support * docs: add changelog entry and bump version * Update docs/how-to/set-up-sitemaps.rst Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> * feat: update sitemap documentation * fix: spelling * Update docs/how-to/set-up-sitemaps.rst * fix: formatting * docs: add link to sitemap config from docs * Update docs/conf.py --------- Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> * fix: RTD versioned sitemaps (#392) * docs: update toctree reference * feat: add sitemap support * docs: add changelog entry and bump version * Update docs/how-to/set-up-sitemaps.rst Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> * feat: update sitemap documentation * fix: spelling * Update docs/how-to/set-up-sitemaps.rst * fix: formatting * docs: add link to sitemap config from docs * Update docs/conf.py * Update set-up-sitemaps.rst * Update conf.py * fix: RTD versioned sitemaps --------- Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> * fix: sitemap (#393) * fix: doc link * fix: remove outdated comment from conf.py * docs: Clarify instructions for sitemaps (#395) * Clarify instructions for sitemaps * fix spelling error * Update docs/how-to/set-up-sitemaps.rst * docs: add guidance about `dirhtml` for sitemaps (#399) Add guidance that instructs the developer to switch to the `dirhtml` builder if necessary. Certain old projects might still be using the `html` builder, which causes sitemap links to be malformed. * conf: drop spurious `ast` import (#398) * fix: branch name in update script (#397) * fix: branch name in update script * update changelog * fix: remove references to obsolete content directory under docs (#400) * docs: clarify instructions for initial setup guide (#401) * docs: add lastmod configuration for sphinx-sitemap (#404) * feat: lastmod in sitemap * fix: spelling * Apply suggestions from code review Co-authored-by: Dave Wilding <tech@dpw.me> --------- Co-authored-by: Dave Wilding <tech@dpw.me> * Add GitHub workflow for checking Contributor Licence Agreement (#403) * add workflow for checking CLA * add CLA requirement to readme * feat: Optimize the Makefile (#388) * Update Makefile Per @desrod's suggestion: Small changes to group .PHONY targets logically together and introduce proper, recursive ${MAKE} instead of statically calling 'make' each time through. More to time! * Update CHANGELOG.md Add changes regarding Makefile logic * feat: improve markdown linting workflow (#379) * fix: markdown linting workflow * fix(ci): match all mardown documents Co-authored-by: Jeremie Deray <deray.jeremie@gmail.com> * fix: switch to pymarkdownlnt --------- Co-authored-by: Jeremie Deray <deray.jeremie@gmail.com> Co-authored-by: Michael Park <michael.park@canonical.com> * feat: Python3 venv detection (#384) * docs/Makefile: do implicit venv support detection Opportunistically try to create the venv and if it fails, hint the user to install `python3-venv`. This avoids spawning another python3 process just for the detection. Signed-off-by: Simon Deziel <simon.deziel@canonical.com> * docs/Makefile: avoid `'` in comments Signed-off-by: Simon Deziel <simon.deziel@canonical.com> * docs/Makefile: prefer `command -v` to `type` Both are shell builtins but `type` is more for human and `command -v` for shell: ``` $ command -v python3; echo $? /usr/bin/python3 0 $ command -v python4; echo $? 1 ``` ``` $ type python3; echo $? python3 is /usr/bin/python3 0 $ type python4; echo $? bash: type: python4: not found 1 ``` Also, `command -v` does not emit anything on `stderr`, it just reflect the availability with its exit code. Signed-off-by: Simon Deziel <simon.deziel@canonical.com> --------- Signed-off-by: Simon Deziel <simon.deziel@canonical.com> * refactor: reference an existing variable (#409) * docs: improve header customisation instructions (#406) Signed-off-by: Minae Lee <minae.lee@canonical.com> * Remove confusing statement on sitemap config (#414) * Update set-up-automated-testing.rst (#415) * Update set-up-automated-testing.rst * Update set-up-automated-testing.rst * Update .custom_wordlist.txt * 1.2.0 release, tidy, and change to vale for spelling (#410) * feat: replace spelling check with vale * chore: pin canonical-sphinx version to 0.5.0 release * chore: remove unnecessary files * chore: bump version * chore: change style guide repo address * docs: clarify syntax guides * docs: document vale exceptions and new spelling config * feat: add URL removal check * chore: remove wordlist * chore: update changelog * fix: linting and checks * fix: linting, spelling * fix: removes URL check * docs: sitemap exceptions * test: correct repo for URL removal check * docs: updates changelog * fix: adds redirect for removed URLs * fix(check-removed-urls): use the pull request base repo for the base … (#1) * fix(check-removed-urls): use the pull request base repo for the base branch * fix: use the full name and not the object * docs: syntax guide reference * chore: remove comment * chore: word additions for vale style linting * chore: unpin canonical-sphinx * Apply suggestions from code review Co-authored-by: Dave Wilding <tech@dpw.me> * Update contributing.rst * Apply suggestions from code review Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com> * docs: add prompt to redirect removed pages in check * chore: remove spellcheck install * feat: keep alternate spellcheck command to warn of deprecation * fix: makefile backticks fix Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> --------- Co-authored-by: Guillaume Beuzeboc <guillaume.beuzeboc@gmail.com> Co-authored-by: Dave Wilding <tech@dpw.me> Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com> Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> * Update woke prereqs in automatic checks doc (#416) * docs: update automatic_checks.rst * fix: update automatic_checks.rst remove woke prereqs * fix: update automatic_checks.rst make list distinction more clear * fix: update automatic_checks.rst fix code block formatting * fix: update automatic_checks.rst punctuation * fix: update docs/reference/automatic_checks.rst typo Co-authored-by: Sara <sara.feijoo@canonical.com> * fix: include suggestions to pr for automatic_checks.rst --------- Co-authored-by: Sara <sara.feijoo@canonical.com> --------- Signed-off-by: Simon Deziel <simon.deziel@canonical.com> Signed-off-by: Minae Lee <minae.lee@canonical.com> Co-authored-by: Robert Krátký <rkratky@gmail.com> Co-authored-by: Dave Jones <dave@waveform.org.uk> Co-authored-by: Robert Krátký <robert.kratky@canonical.com> Co-authored-by: tang-mm <3333407+tang-mm@users.noreply.github.com> Co-authored-by: Artem Konev <141050460+akcano@users.noreply.github.com> Co-authored-by: Andreia <andreia.velasco@canonical.com> Co-authored-by: Marek Suchánek <marek.suchanek@protonmail.com> Co-authored-by: Sally <sally.makin@canonical.com> Co-authored-by: Michael DuBelko <michael.dubelko@canonical.com> Co-authored-by: Michał Sawicz <michal@sawicz.net> Co-authored-by: Dave Wilding <david.wilding@canonical.com> Co-authored-by: Dave Wilding <tech@dpw.me> Co-authored-by: JordanMG13 <91559220+JordanMG13@users.noreply.github.com> Co-authored-by: Stephen Mwangi <mail@stephenmwangi.com> Co-authored-by: Jeremie Deray <deray.jeremie@gmail.com> Co-authored-by: Simon Deziel <simon.deziel@canonical.com> Co-authored-by: Charles Uneze <charlesniklaus@gmail.com> Co-authored-by: Minae Lee <minae.lee@canonical.com> Co-authored-by: Erin Conley <erin.conley@canonical.com> Co-authored-by: Guillaume Beuzeboc <guillaume.beuzeboc@gmail.com> Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com> Co-authored-by: Ashley Cliff <ashley.cliff@canonical.com> Co-authored-by: Sara <sara.feijoo@canonical.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
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.
CHANGELOG.mdwith relevant non-documentation file changes?By default, the
DavidAnson/markdownlint-cli2-actionaction only lints Markdown files in the base directory, so I've updated it to run againstdocs/*.mdas well.Added a
make lint-mdtarget to lint Markdown locally.I've added a blank line between the ref targets and the headings because the current markdownlint config requires blank lines around headings (rule
MD022). I've confirmed that the links still work okay.This PR is basically a follow-up on #297.
@SecondSkoll @k-dimple