Coleman's Markdown Style Guide

markdown_style.md

This guide has moved.

---

Overview

This guide is for people who deal with software: programmers, sysadmins, etc.

Hard Wrapping

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

File Paths

Represent file paths with bold text when they are embedded in other Text. 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

Step by Step Instructions

Avoid numbered lists for step by step instructions that have commands interspersed.

For example, I'd ask you to run this command

./my-script.sh

Then I'd ask you to run another.

ls | grep pem

Note: notes about what output to look for can be provied below, in italics.

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.

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, but
  this means dropping support for any version below 7.4
* Fixed bug that made all text purple

Headings

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

## An H2 Header

To this

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

Also, 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. Deep and complex nesting into H3, H4, and others makes the document difficult to follow in terminal environments.

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.

Structured lists are sometimes a good alternative to tables. For example:

• 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.