Add "Verse" entry to Proposed Extensions wiki

Open Beginner friendly
#838 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Quiet
Tech stack
markdown
Domain
documentation

Research direction

Read the issue and its linked CommonMark discussion, then locate the Proposed Extensions wiki page and review its existing entry format. Add the supplied Verse proposal with its syntax, rationale, and open questions, or follow the wiki's documented contribution process if direct editing is unavailable. Done means the proposal appears on the wiki without losing its Markdown examples.

Written by the indexing model from the issue text.

Description

I'd like to propose a new Verse extension for the Proposed Extensions wiki, but I don't have write access.

Discussion:
https://talk.commonmark.org/t/semantic-block-for-poetry-lyrics-with-optical-alignment-the-longest-line-rule/9091/6


Verse

The goal is not to introduce new rendering capabilities, but to provide a semantic representation for an existing textual form.

Problem

Markdown has no block-level construct for representing verse (poetry, song lyrics, hymns, psalms, dramatic verse). Existing workarounds—blockquotes, trailing double spaces, and fenced code blocks—either carry the wrong semantics or rely on formatting conventions that editors and linters routinely strip.

Proposed syntax

```verse
This is the first line.
This is the second line.
This is the longest line of the stanza.

This is another stanza.
```

A blank line inside the block starts a new stanza. All other line breaks are preserved exactly as written. Inline Markdown formatting continues to work inside verse lines.

Illustrative HTML output

<div class="verse">
  <p>
    This is the first line.<br>
    This is the second line.<br>
    This is the longest line of the stanza.
  </p>
  <p>
    This is another stanza.
  </p>
</div>

Each stanza becomes a <p>, with lines separated by <br>. The HTML representation is illustrative and open to discussion.

Why not fenced code blocks?

Verse is ordinary natural-language text whose structure is defined by meaningful line and stanza boundaries. Fenced code blocks identify source code (or code-like content), not verse, so they express the wrong semantics even if they preserve formatting.

Why "verse" and not "poem"?

"Poem" names a work, while "verse" describes a textual form. The proposed block represents a line-and-stanza structure that also applies to song lyrics, hymns, psalms, and dramatic verse. Although the term "verse" is used by some Bible markup tools to mean a numbered scripture verse, that usage is unrelated and doesn't conflict with verse as a fenced-block info string.

Open questions

  • Should long lines wrap normally, or use a hanging indent to distinguish a wrapped continuation from a new verse line?
  • Should presentation be entirely left to CSS, or should a reference stylesheet recommend common verse layouts?

Could someone with wiki edit permissions add this proposal to the Proposed Extensions wiki, or let me know if there's a different process I should follow?

Dominant language
Python
Stars
5.1k
Forks
358
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from commonmark/commonmark-spec

All issues in commonmark/commonmark-spec

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.