Skip to content

docs: fix lists swallowed into the preceding paragraph - #275

Merged
dimitri-yatsenko merged 1 commit into
mainfrom
docs/fix-swallowed-lists
Sep 10, 2026
Merged

docs: fix lists swallowed into the preceding paragraph#275
dimitri-yatsenko merged 1 commit into
mainfrom
docs/fix-swallowed-lists

Conversation

@dimitri-yatsenko

Copy link
Copy Markdown
Member

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:

**Addressing schemes:**
- **Hash-addressed**: Path from content hash. Automatic deduplication.
- **Schema-addressed**: Path mirrors database structure. One location per entity.

renders as a single run-on <p> with literal dashes:

<p><strong>Addressing schemes:</strong>
- <strong>Hash-addressed</strong>: Path from content hash. Automatic deduplication.
- <strong>Schema-addressed</strong>: Path mirrors database structure. One location per entity.</p>

Neither mkdocs build nor 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:

file count
how-to/choose-storage-type.md 30
reference/errors.md 16
reference/specs/query-algebra.md 11
reference/specs/autopopulate.md 9
reference/specs/data-manipulation.md 9
reference/specs/object-store-configuration.md 8
reference/specs/type-system.md 8
how-to/migrate-to-v20.md 8
reference/specs/job-metadata.md 7
reference/specs/npy-codec.md 7
reference/specs/table-declaration.md 5
how-to/use-npy-codec.md 5
how-to/use-plugin-codecs.md 5
reference/specs/codec-api.md 4
reference/specs/master-part.md 4
(8 more with 1–3 each) 11

Guard against recurrence

scripts/check_markdown_lists.py + a Markdown Lint workflow. This is detectable in source without a build, so the job is just a checkout and one script. It takes --fix to 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:

swallowed <li> loose items
before 149 2377 71
after 0 2870 71
delta −149 +493 +0

493 list items recovered, no tight list turned loose, --strict passes. The checker run against the pre-fix codec-api.md flags 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-api addressing-schemes list documents only Hash and Schema, but the table directly above it also has a Reference scheme for <filepath@>. Adding that line is a content decision, so I left it.

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.
@dimitri-yatsenko dimitri-yatsenko added the documentation Improvements or additions to documentation label Sep 10, 2026
@dimitri-yatsenko
dimitri-yatsenko merged commit daf6dd7 into main Sep 10, 2026
3 checks passed
@dimitri-yatsenko
dimitri-yatsenko deleted the docs/fix-swallowed-lists branch September 10, 2026 18:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants