Markdown for documentation

Why this matters

Documentation in a repository is written in Markdown: READMEs, guides, changelogs, and also every issue, merge request description and comment on GitLab and GitHub. Markdown is plain text, so Git can show exactly what changed and reviewers can comment on a line. Fifteen minutes of syntax covers almost everything you will ever write.

The syntax

Markdown is text with a few punctuation conventions. What you type on the left; what readers see on the right.

# Page title (one per file)

## Section

### Subsection

A paragraph is one or more lines of text.
Lines in the same paragraph join together.

A blank line starts a new paragraph.

**bold**, *italic*, `inline code such as git status`

Use inline code for commands, file names (`README.md`) and values.

- A bullet
- Another bullet
  - Indented two spaces: a nested bullet

1. First step
2. Second step
3. Third step

[Text of the link](https://gitlab.com)
[A file in the same repository](docs/faq.md)
[A section of this page](#section)
![Alternative text for the image](docs/images/logo.svg)

Three backticks, the language name, the code, three backticks:

```bash
git status

```markdown title="Tables, quotes, rules"
| Column | Another column |
|---|---|
| a cell | another cell |

> A quotation or a highlighted note.

---

The language name after the opening backticks (bash, python, yaml, markdown) turns on syntax colouring; leave it out for plain output. Inside a code block nothing is interpreted, which is why commands and file contents belong there.

Two rules cause most rendering surprises: put a blank line before a list, a table or a code block, and put a space after # in headings and after - in bullets.

What GitLab and GitHub add

Both platforms extend Markdown ("GitLab Flavored Markdown", "GitHub Flavored Markdown") with things you will use in issues and merge requests:

In merge request descriptions, Closes #12 (or Fixes #12) is not decoration: it closes the issue automatically when the merge request is merged.

README conventions

A README is the front door of a project. Readers expect, in this order:

1. Title and one-line description. What the project is, in a sentence.
2. Getting started. How to install and run it, with commands in code blocks.
3. Usage. The most common things to do with it.
4. Where the docs are. Links into docs/.
5. How to contribute. A link to CONTRIBUTING.md.
6. Licence and contact, if relevant.

Look at the playground's README.md: in about fifty lines it follows most of that shape, with the title and description, what is in the folder, how to run it, how to run the tests, links to the documentation, and the team. It has no separate contributing section, because it links CONTRIBUTING.md from the documentation list instead, and no licence section, because the project is fictional. That is normal: the order above is a convention people expect, not a form to fill in.

Previewing

$ npx --yes markdownlint-cli "**/*.md" --ignore node_modules

Lint rules you will meet

Pipelines often run markdownlint on documentation. The rules that catch most people:

The playground's .markdownlint.json turns off the line-length rule (MD013), a common team choice.

Common mistakes

• A list glued to the paragraph above. Without a blank line, the bullets render as one paragraph. Add the blank line.
• Tabs for nesting. Use two (or four) spaces to indent nested bullets; tabs render unpredictably.
• Absolute links to files. [FAQ](/Users/ana/trailguide/docs/faq.md) works only on Ana's machine. Use paths relative to the file: [FAQ](faq.md).
• Screenshots of code. Paste the code in a code block; images cannot be searched, copied or diffed.
• Editing the rendered page. On GitLab and GitHub you edit the source text; the rendering is automatic.

## How do I run the tests?

1. Open a terminal in the `trailguide` folder.
2. Run `python3 -m unittest discover -s tests -v`.

See [Getting started](getting-started.md) for installing Python.