# Natron Markdown Style Guide

This is a style guide for Markdown for all contributors to [Natron](https://natrongithub.github.io), the free and open-source compositing suite.

## TL;DR

We want to keep our Markdown clear and easy to read, even when displayed inside a text editor. That's why we urge everyone to follow these very simple rules in writing Markdown.

Additionally, we have built a markdown linter and formatter *(WIP)* that attempts to point out and automatically correct any issues based on this style guide. We highly recommend that everyone use this tool to validate their markdown. Get it [here](#).

:warning: Note that NMD-Lint (the aforementioned Markdown formatter) is not finished yet and is in a WIP state.

## Basic conventions for Markdown files

- Denote **bold** text using the asterisk format: `**bold text**`.
- Denote *italic* text using the asterisk format: `*emphasized text*`.
- Keep all text flush to the left side of the document, and do not indent text unless you have a good reason to.
- Do not add excess spaces, trailing spaces, and excess empty lines.
- Always add a full stop character (`.`) after each line.

## Headings

- Header text must compose of one `#` character and the associated heading text, with no closing `#` character.
- Headers must be preceded and followed by a newline except at the beginning of a file.
- Below are some exemplar headings:

# Header 1
## Header 2
### Header 3

## Horizontal Rules

The convention for horizontal rules in this style guide is to use three underscores, like so:

* * *

Avoid using hyphens or underscores for the purpose of creating horizontal rules, because they can display badly when line-wrapped by text editors.

## Lists

- **List items** must be indented 4 spaces further than their parent. Set indent in your text editor to 4 spaces in your preferred editor to enforce this rule.
- Unordered list Items should use `-` instead of `*`.

This is arbitrary text, an unordered list begins on the next line.
    - list item 1
    - list item 2
        - sub-list item

- The first level of list items must not be preceded by a newline, unless preceded by a heading.
- All lists must be followed by newlines, but sub-lists do not need a newline.

This text precedes a list of things.
      - list item 1
      - list item 2
          1. sub-list item 1
          2. sub-list item 2
      - list item 3
      - list item 4

This is text of any kind that follows a list.

## Code

- **Inline code** must use single backticks and must not have spaces between the backtick characters and the code.

# Bad
` .this_is_wrong `

# Good
`.this_is_good`

- **Fenced code blocks** must be preceded and followed by a newline. It is strongly recommended to specify the programming language of the code, *unless* if the code is in a plaintext format and written as prose (e.g. Markdown or reStructured Text)
- If the code is in a plaintext format, syntax highlighting is optional and can be added based on personal discretion
- Generally avoid adding syntax highlihgint to plaintext code blocks where the words `this` and `is` appear or code blocks that contain lots of numbers within prose (eg. `within page 1, 3, and 5`)
- When used inside *list items*, **fenced code blocks** must be indented as if they were one level deeper that the list item that contains them.

  - This list item contains a fenced code block.
  - Let's show how it might interact with a list.

.code-example {
property: value;
}

There is a newline above this paragraph because it is both the end of a
list and because it follows a fenced code block.

## Tables

- Tables should not be used if other forms of formatting may better communicate the information; this is because tables must be meticulously formatted and tabular content can be distorted due to line wrapping.
- It is highly recommended to use [this table generator](https://www.tablesgenerator.com/markdown_tables) to ensure proper formatting.
- Table column width should be determined by the longest cell in the column; again, though, formatting should best be done using automated tools such as table generators.
- Always format tables so they are readable in pre-processing.

# This is completely unreadable, although it is technically valid.
table header | other table header
--- | ---
table data | other table data

- Use a leading pipe always, and a trailing pipe as well, unless if the table contains long-form content over ~35 characters
- In the first row of a table, which contains the table labels, ensure that each label has a space before and after a pipe

# Good
| Category | Type | Value |
|----------|------|-------|

# Bad
|Category|Type|Value|
|--------|----|-----|

- Tables must always be preceded and followed by newlines.

### Table example:

*This table meets all the criteria:*

| Group                     | Domain          | First Appearance |
|---------------------------|-----------------|------------------|
| ShinRa                    | Mako Reactors   | FFVII            |
| Moogles                   | MogNet          | FFIII            |
| Vana'diel Chocobo Society | Chocobo Raising | FFXI:TOAU        |

| Group | Domain | First Appearance |
|---------------------------|-----------------|------------------|
| ShinRa | Mako Reactors | FFVII |
| Moogles | MogNet | FFIII |
| Vana'diel Chocobo Society | Chocobo Raising | FFXI:TOAU |

## URL Linking

Though the majority of Natron's Markdown content uses GitHub Markdown, which automatically turns valid links into formatted links, we encourage everyone to enclose a link in angled brackets `<like so>`.

This is a correct link: <http://example.org/>

This is a correct link: <http://example.org/>

For link labels, place the label text in squared brackets `[ ]` and the link itself in curved brackets `( )`

This [link with a label](https://www.markdownguide.org) is correct.

This [link with a label](https://www.markdownguide.org) is correct.

## Strikethrough

To create a strikethrough, add two tildes on either side of your intended content, like so:

### Strikethrough Exemplar

This PR ~~changes the spelling of "aluminum" to aluminium~~ spell changes cancelled.

This PR ~~changes the spelling of "aluminum" to aluminium~~ spell changes cancelled.

## Quotes

- Quotes should be used sparingly, and specifically only for quotes of textual or spoken content; they should ideally not be used for warnings, notes, or other forms of expositional content.
- The correct quote syntax is to use a right angled bracket `>`, followed by a space and a hyphen.
- Multiple-line quotes should include a right angled bracket followed by a space for expressing a newline.
- Quotes should be always be preceded and ended by newlines.

### Exemplar Quote

This quote fully adheres to our standards:

> And your position in this, Captain? Hold it, Aaron!
>
> *William Riker*

> And your position in this, Captain? Hold it, Aaron!
>
> *William Riker*

## Task Lists

* Before creating a task list, consider alternative formatting options, as the teask list syntax is not universally supported.
* Places where task lists should be used include all Markdown files hosted on GitHub and HackMD.
* In other locations, it is advised to not use them.

The correct syntax for a task list is a hyphen, followed by a space enclosed with a bracket `- [ ]`. This is a demonstration of the correct syntax:

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

And this is the rendered result:

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media