Lists and Tasks

Unordered, ordered, nested, and task lists — plus a definition-list pattern using bold leads.

2 min readshowcasereference

Lists are the workhorse of technical writing. The renderer supports the three standard markdown list types plus GitHub-style task lists.

Unordered lists

Use - (or *) for bullet points when the order doesn't matter.

  • The first item.
  • The second item, which is a bit longer and wraps onto another line so you can see how the text aligns with the bullet above it.
  • The third item.

Ordered lists

Use 1. for numbered steps when the order is meaningful. The renderer renumbers automatically — you can write 1. for every item if you want.

  1. Sign in to your account dashboard.
  2. Open the Downloads tab.
  3. Click Generate URL next to the latest release.
  4. Copy the URL — it's signed and expires in 15 minutes.
  5. Paste it into your curl command on the server.

Nested lists

Indent by two spaces (or four — both work) to nest. Mix ordered and unordered freely.

  • Customer-facing modules
    • Clients
    • Sales
    • Tickets
  • Internal modules
    • Reports
    • API Keys
    • Notifications
  • Real-time modules
    • Auction
    • Calendar
    • Notifications

Ordered nested under unordered:

  • Provisioning steps, in order:
    1. Allocate the Plesk subscription.
    2. Register the domain.
    3. Wait for DNS propagation.
    4. Install BRAD and run migrations.

Task lists

Use - [ ] for unchecked and - [x] for checked. Handy for pre-flight checklists.

  • Buy a license.
  • Provision a server.
  • Configure DNS.
  • Run the first install.
  • Create the superadmin user.
  • Invite the rest of the team.

Nested task lists work too:

  • Set up your install
    • Run bun install
    • Run bun run db:migrate
    • Run bun run start
  • Configure your domain
    • Add the A record
    • Wait for propagation

Definition-list-style pattern

Markdown doesn't have native definition lists, but bold-led paragraphs read well and require no special syntax.

License key The unique identifier for your install. Format: BRAD-XXXX-XXXX-XXXX-XXXX. Find it on your account dashboard or in the receipt email.

Re-check interval How often a running install phones home to verify its license. Default 15 days, with a 5-day grace window before the install pauses.

Addons A comma-separated list of module slugs the license entitles. Reflected in real time — adding a module on the headless side enables it on the install at the next check.

For two or three terms, the bold-led paragraph pattern reads better than a table. For more, switch to a table so the values align.