Skip to content

doc: clarify that a sublist needs a blank line#400

Open
dereuromark wants to merge 1 commit into
jgm:mainfrom
dereuromark:docs/list-sublist-blank-line
Open

doc: clarify that a sublist needs a blank line#400
dereuromark wants to merge 1 commit into
jgm:mainfrom
dereuromark:docs/list-sublist-blank-line

Conversation

@dereuromark

Copy link
Copy Markdown
Contributor

Problem

The behavior is fully specified, but split across two distant sections, and the connection is easy to miss.

The Block syntax preamble states the governing rule:

Paragraphs can never be interrupted by other block-level elements, and must always end with a blank line.

The List item section, however, only describes lazy continuation and says an item is "one or more lines, indented relative to the list marker." A reader there naturally expects

- a
  - b

to nest. It does not: because the indented - b would interrupt the open paragraph a, it folds in as lazy continuation, so this is a single-item list. A blank line is required to nest:

- a

  - b

This trips up newcomers (and is a common point of confusion when comparing djot to Markdown/CommonMark, where the first form nests).

Change

Add a short example to the List item section that makes the consequence of the non-interruption rule explicit, contrasting the no-blank-line case (single item) with the blank-line case (nested sublist), and pointing back to the Block syntax rule.

Verified against the reference (djot.js 0.3.2):

  • - a / - b produces one <li> containing the paragraph.
  • - a / blank / - b produces a nested <ul>.

Docs only: edits doc/syntax.md; doc/syntax.html is regenerated from it via the make rule (not committed here). Opened as a draft for your review of wording and placement.

The List item section shows lazy continuation but never the consequence
of the global rule (Block syntax) that a paragraph can never be
interrupted: an indented list marker directly after paragraph text folds
in as lazy continuation rather than starting a sublist. Add a short
example contrasting the no-blank-line case (single item) with the
blank-line case (nested sublist), since the connection between the two
sections is easy to miss.

Edits doc/syntax.md only; doc/syntax.html is regenerated from it via make.
@dereuromark dereuromark marked this pull request as ready for review June 16, 2026 14:55
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.

1 participant