docs: fix lists swallowed into the preceding paragraph - #275
Merged
Conversation
A Markdown list needs a blank line after a paragraph lead-in. Without
one it renders as a single run-on <p> with literal dashes instead of a
<ul> -- reported on reference/specs/codec-api, "Addressing schemes".
Neither mkdocs build nor the existing checks warn about this, so the
pages just quietly looked wrong. A sweep of the built output found 149
occurrences across 23 files, all the same shape: a bold lead-in
("Characteristics:", "Common causes:", "Rules:") followed immediately
by list items. choose-storage-type alone had 30.
Insert the blank lines, and add scripts/check_markdown_lists.py plus a
Markdown Lint workflow so the shape cannot come back. The checker takes
--fix to apply the spacing.
Only top-level lists directly under an ordinary paragraph are touched.
Lists already inside a list block -- including ones whose previous line
is a wrapped continuation of an earlier item -- are left alone, so tight
lists stay tight: the build gains 493 list items with no change to the
loose-item count, and passes --strict.
MilagrosMarin
approved these changes
Sep 10, 2026
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
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.
Reported: the "Addressing schemes" bullet list on https://docs.datajoint.com/reference/specs/codec-api/ is broken.
Root cause
A Markdown list needs a blank line after a paragraph lead-in. Without one, this:
renders as a single run-on
<p>with literal dashes:Neither
mkdocs buildnor the existing checks warn about this, so the pages just quietly looked wrong.Scope
Not one page. A sweep of the built output found 149 occurrences across 23 files, all the same shape — a bold lead-in (
Characteristics:,Common causes:,Rules:,Best for:) followed immediately by list items:how-to/choose-storage-type.mdreference/errors.mdreference/specs/query-algebra.mdreference/specs/autopopulate.mdreference/specs/data-manipulation.mdreference/specs/object-store-configuration.mdreference/specs/type-system.mdhow-to/migrate-to-v20.mdreference/specs/job-metadata.mdreference/specs/npy-codec.mdreference/specs/table-declaration.mdhow-to/use-npy-codec.mdhow-to/use-plugin-codecs.mdreference/specs/codec-api.mdreference/specs/master-part.mdGuard against recurrence
scripts/check_markdown_lists.py+ aMarkdown Lintworkflow. This is detectable in source without a build, so the job is just a checkout and one script. It takes--fixto apply the spacing.Only top-level lists directly under an ordinary paragraph are reported. Lists already inside a list block — including ones whose previous line is a wrapped continuation of an earlier item — are left alone, so tight lists stay tight. (My first pass got this wrong and made 10 existing items loose; the state tracking now prevents that.)
Verification
Built before and after with
--strict, comparing content-area lists only:<li>493 list items recovered, no tight list turned loose,
--strictpasses. The checker run against the pre-fixcodec-api.mdflags all 4 of its sites including line 529, the reported one.Note for review
The 149 changes are mechanical (blank-line insertion only, no prose touched), so the diff is best read with whitespace shown. One content gap I did not touch: the
codec-apiaddressing-schemes list documents only Hash and Schema, but the table directly above it also has aReferencescheme for<filepath@>. Adding that line is a content decision, so I left it.