TopolearnHeadings and lists give a README or design doc its skeleton and make it skimmable.
Headings start with one to six # characters followed by a space: # Title, ## Section, ### Subsection. Use a single # heading per document for the title and don't skip levels; tools build tables of contents and anchors from them. (An older "setext" style underlines a heading with === or ---; you'll see it but needn't write it.)
Bullet lists use -, * or + followed by a space. Pick one marker and stick to it; changing the marker starts a new list.
Ordered lists use a number followed by . or ). Only the first number matters: it sets the start, and the rest are numbered sequentially, so writing 1. on every line is a common style that keeps diffs small when items move.
Nesting: indent a sub-list so that its marker lines up with the content of the parent item, which is two spaces under - and three under 1. . Paragraphs and code blocks inside an item use the same indentation.
Leave a blank line before a list that follows a paragraph. In CommonMark a bullet list can interrupt a paragraph, but an ordered list can only do so if it starts at 1, and many other renderers require the blank line anyway.
Example
# Project title
## Installation
1. Clone the repository
1. Install dependencies:
- Python 3.12+
- `uv` or `pip`
1. Run the tests
## Features
- Fast startup
- Plugins
- Loaded from `plugins/`
- Hot-reloaded in development
<!-- the ordered list renders as 1. 2. 3. even though every item says 1. -->Remember
- # to ###### followed by a space make headings; one # title per document
- - for bullets, 1. for numbered lists; only the first number matters
- Indent sub-lists to line up with the parent item's text
Watch out for
- Writing #Heading without a space, which CommonMark renders as a plain paragraph.