Skip to content

Markdown convention: bless trailing-backslash hard line breaks #164

Description

@ptr727

The AGENTS.md "Documentation Style -> Markdown" rule says "One logical paragraph per line; no hard-wrap line-length limit." GitHub Copilot's PR review reads this as forbidding trailing-backslash (\) hard line breaks and repeatedly flags them on README badge / status / license blocks (stacked one-per-line entries that use \ or trailing whitespace as <br>).

These hard breaks are intentional and read better than invisible trailing-double-spaces, and they aren't paragraph wrapping. The current wording causes avoidable review friction every round.

Suggestion

Clarify the rule to explicitly allow \ for intentional hard line breaks within a block, preferred over trailing whitespace. Wording used downstream:

One logical paragraph per line; no hard-wrap line-length limit. For an intentional hard line break within a block - stacked badges, status, or license lines - end the line with a trailing backslash (\); this explicit form is preferred over trailing whitespace for readability and is not treated as a paragraph split.

This keeps the no-hard-wrap intent while stopping the false-positive review flags.


Surfaced in ptr727/ESPHome-NonRoot (see ptr727/ESPHome-NonRoot#63); applied downstream already.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions