Markdown - Style Guide


use blockquotes for quotations and current page titles (say, wizard steps)

  1. Step 1: Create Policy

NOTE: backticks are not used.

use table to specify context and path

  1. https://kramdown.gettalong.org/syntax.html#tables
context
service, web page, program, etc.
path
location within context

=> always add header and at least one row - even if they are empty (otherwise Prettier breaks formatting of Markdown tables - see Prettier).

it’s possible to add path element description in parentheses: usually it’s UI element which represents path element itself (say, menu item or button) or UI element containing described path element (say, top menu).

path might include action or setting as a final node (say, menu item). if there are multiple settings, they are specified separately as a list:

iTunes Connect
PreferencesKeysHotkey

NOTE: backticks are used for exact names.

keep path on a single line (or else table won’t be rendered) but it’s allowed to use multiple table rows each row containing the path on a separate screen (window or page). or else multiple table rows can be used to split path into 2 parts - high-level part and the one specifying exact location of UI element.

use comment with arrow to specify return value

~N[2019-09-01 03:00:00]
|> Timex.shift(months: 1)
# => ~N[2019-10-01 03:00:00]

use this format instead of pry> or iex> prompts where possible.

use comment line followed by blank line to specify file path inside code block

  1. https://sass-lang.com/guide
  2. https://rossta.net/blog/from-sprockets-to-webpack.html
// yarn.lock

"@rails/webpacker@3.5":
  version "3.5.3"

use this format instead of specifying file path in front of cobe block in italics (yarn.lock) where possible - probably except for logs (there are no comments in logs).

https://rossta.net/blog/from-sprockets-to-webpack.html#deploying-with-capistrano-and-nginx

set public/packs and node_modules as shared directories to ensure Webpack build output and NPM package installation via Yarn are shared across deploys

in some cases when all quotes within section have the same source (and its link is given at the beginning of the section), the link inside quotes can be omitted.

  1. https://stackoverflow.com/a/32950454/3632318

insert resource links if linked resource is related to section subject and can be useful in one way or another - it doesn’t have to be quoted inside this section or treat the subject directly.

if link is already used inside quotes and information from linked resource is not used outside these quotes, the link can be omitted at the beginning of the section.

use backticks for shell commands but not for proper names

psql (shell command) vs. PostgreSQL (proper name).

try to minimize usage of backticks in headers

say, it’s okay to use psql in main text but it’s better to omit backticks when it’s used in any header.

still in many cases it’s necessary to use backticks to avoid ambiguity (say, for shell commands with arguments - that is when they contain spaces).