Surface Kramdown warnings by breaking pipeline
Each month in our monthly chores list, we have to look for Kramdown (markdown formatting) warnings and fix them. After working on a solution in Fix Kramdown Warnings in GraphQL documentation (gitlab#368320 - closed), I'm questioning why we allow docs builds to complete with these warnings. In my experience, they DO cause visible formatting problems on the page they're in, and that feels (to me) like something we should fail a pipeline on, rather than silently cleaning up after the fact.
An example from Fix Kramdown Warnings in GraphQL documentation (gitlab#368320 - closed) (thanks @claytoncornell) is the compile_dev
job (https://gitlab.com/gitlab-org/gitlab-docs/-/jobs/2743064324). However, that warning is after the fact; I think the real fix is to contribute a change to the docs-lint links
job (example https://gitlab.com/gitlab-org/gitlab/-/jobs/2753270301) - the warnings look like this:
kramdown warning(s) for <Nanoc::Core::CompilationItemRepView item.identifier=/ee/api/graphql/reference/index.md name=default>
No link definition for link ID '`production`' found on line 1
The first line of a warning always starts with kramdown warning
and the next line tells where to look in the file. Capturing these lines as part of running the job, and making bundle exec nanoc
return an error (rather than success) could catch the problem when it happens, rather than leaving it for monthly chore cleanup.
Related issues and merge requests
- Related to Fix Kramdown warnings in GraphQL defs and docs (gitlab!94865 - merged) where I'm proposing fixes
- Related to Fix Kramdown Warnings in GraphQL documentation (gitlab#368320 - closed) where Clayton documented the problems
- Related to Docs project maintenance tasks - July 2022 (technical-writing#639 - closed) - the monthly chore assignment where Clayton encountered the problem