Coleman's Markdown Style Guide

15 Jul, 2024

This guide is for people who deal with software: programmers, sysadmins, etc. It's a list of rules and the reasoning behind those rules.

Hard Wrapping

Hard wrap all markdown text files between 80-100 characters.

Relying on automatic wrapping is arguably easier for the writer, but only if they've already located the portion of the document they want to edit. If you are using a wide screen, and an entire paragraph appears on one long line, the soft-wrap in your editor may not even be used. Why make me scan horizontally to find the portion of markdown I want to edit?

Hard wrapping makes git diffs more useful, because hard wrapping makes line numbers more meaningful. If a long, multi- sentence paragraph appears on one line in a file, I can't say things like, "we should fix the typo on line 150".

Hard wrapping makes the plain text structure of the document resemble the pretty-printed rendered HTML that readers will view on GitHub. And that's something you should be thinking about when editing markdown.

File Paths

Represent file paths with bold text when they are embedded in other prose text. Don't use backticks.

Prefer this:

Carla's public key is located at /home/carla/.ssh/id_ed25519.pub

Over this:

Carla's public key is located at /home/carla/.ssh/id_ed25519.pub

This is probably a controversial one.

Step by Step Instructions

This recommendation is the one I feel most strongly about.

Avoid numbered lists for step by step instructions that have commands interspersed. Use regular prose mixed with code blocks.

Here's how it looks. For example, I'd ask you to run this command

./my-script.sh

Then I'd ask you to run another.

ls | grep pem

And then: notes about what output to look for can be provided below the command, in italics.

That's it. The key takeaway here is to avoid numbers or bullets for each "step". The rendering of lists with interspersed code blocks is often finicky, and adding or removing steps is harder when it has to conform to a list structure.

If you need to communicate some kind of conditional step, use headings.

## Testing

Testing our project is easy.

### Install Test Reporting Tool (optional)

To parse test output into HTML reports, you need the
test parser.

    apk add the-test-parser

Otherwise, proceed.

### Running Tests

Run the following from the root of the repo. Test may
take around 10 minutes on a decent laptop.

    testing-tool --verbose=true

File Names

Markdown has the .md extension, and file names should be all caps, unless they are part of a directory with mostly markdown files, e.g. a static site.

See the following example directory structures.

/my-project
  .circleci
  main.go
  CONTRIBUTING.md
  README.md
  .gitignore

vs

/my-static-site
  /content
    about.md
    dough_philosophy.md
    how_to_bake_bread.md
    welcome.md
  build.sh
  README.md

Bulleted Lists

Always use asterisks to create lists, no matter how nested. Preserve exactly one line of whitespace above a bulleted list. Indent lists with two spaces.

Asterisks just look better to me.

Shopping list:

* Food
  * bananas
  * apples
* Other
  * toothpaste
  * floss

If a list contains long lines of text, the hard-wrapping rule still applies. Example:

## Release 1.2

* Fixed the thing that was bugging all our customers
* Fixed a performance regression that was only visible when 
  using MySQL. This means dropping support for 7.4 or below.
* It also means hard wrapping the previous bullet point

Headings

Do not use === or --- to create underline-style headers.

Prefer this

## An H2 Header

To this

An H2 Header
------------

Heading Structure

Headers are the main tool of document structuring in Markdown.

H1 headers should be used sparingly.

In README documents, a good pattern is to have exactly one H1 header at the top of the document announcing the project's name with a brief summary below.

# nginx

Nginx is a high-performance web server and reverse-proxy written in C.

Note: Leave one space below a header entry, always.

In general, H2 headers should be the most common header type in your documents, and you should anticipate using them liberally.

Deep and complex nesting into H3, H4, and others makes the document difficult to follow in terminal environments, and usually don't look great on the web, either.

If you find yourself nesting a lot, consider creating a new document. Hoist your H3's into H2's, with one H2 hoisted to a single top-level H1 at the beginning of the document.

That's not always practical, so use your judgement. Just nest headers sparingly.

Tables

Here's my take on Markdown tables.

Don't use tables.

Avoid them. They're miserable to maintain, and look horrible in terminals unless you keep them lined up perfectly, and you're not going to do that. If you absolutely must have a table, consider using an automated tool for formatting. Alternatively, consider using HTML, which will probably be easier to maintain.

I don't think they look that great on the Web, either.

Alternatives to Tables

Structured lists are sometimes a good alternative to tables.

Consider this list of config attributes.

• insecure_skip_verify - boolean - If true, do not validate the peer's certificate
• address - string - A TCP address of the form host:port
• ui - boolean - If true, serve the web UI. False by default.

This list is a perfectly fine alternative to the following table.

With hand-maintained tables, the juice ain't worth the squeeze.

Conclusion

These rules aren't perfect, but whether you follow them or not, take some time to think about how you (and your colleagues) should represent information, so that the documents you produce look consistent and are easy to maintain.

#writing