Markdown - Style Guide02 Mar 2018
- use blockquotes for quotations and current page titles (say, wizard steps)
- use table to specify context and path
- use comment with arrow to specify return value
- use comment line followed by blank line to specify file path inside code block
- insert resource link followed by a blank line inside quotes
- insert resource links at the beginning of the section
- use backticks for shell commands but not for proper names
- try to minimize usage of backticks in headers
use blockquotes for quotations and current page titles (say, wizard steps)
- Step 1: Create Policy
NOTE: backticks are not used.
use table to specify context and path
- service, web page, program, etc.
- location within context
context is specified in a table header, paths are specified in table rows:
path only (prefer to always specify context though):
=> 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:
Show/hide iTerm2 with a system-wide hotkey
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
iex> prompts where possible.
use comment line followed by blank line to specify file path inside code block
// yarn.lock "@firstname.lastname@example.org": 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).
insert resource link followed by a blank line inside quotes
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.
insert resource links at the beginning of the section
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).