Skip to content

Latest commit

 

History

History
170 lines (124 loc) · 5.19 KB

Markdown.md

File metadata and controls

170 lines (124 loc) · 5.19 KB
Raw

AdGuard Go Team Markdown guidelines

Note

Some rules are deprecated. New code should instead use markdownlint and follow the configuration and guidelines favored by the Content Team.

See https://github.com/AdguardTeam/KnowledgeBaseDNS/blob/master/.markdownlint.json and https://github.com/igorshubovych/markdownlint-cli.

  • §

    [!WARNING]

    This rule is deprecated. See message at the beginning of the document.

    Align things to multiples of four columns. Leave two spaces between the marker and the content. Below are some examples:

    • § Lists:

       *  Item one.
 *  Item two.
      1.  Item one.
1.  Item two.

    • § Headers:

       #  Article
##  Section
   ###  Subsection
  ####  Subsubsection
 #####  Subsubsubsection
######  Subsubsubsubsection

    • § Quotes:

       >  This is a quote from some other source. This is a rather long quote
 >  to show exactly how long quotes must be formatted.

    • § Embedded HTML:

      <p align="center">
    <img src="https://cdn.example.com/image.svg"/>
</p>

  • § Do not ever change elements' IDs. That breaks people's links. Strive to give links to moved content.

  • § Generate IDs for list items. To generate a new random ID, use something like the following Unix command:

    od -A n -N 4 -t x4 < /dev/urandom

  • § In numbered lists, use 1. as the list item marker.

  • § Only use tight lists—that is, lists without empty lines between the items—for lists of short numeric information or tables of contents. Use loose lists—lists with empty lines between the items—for everything else.

    An example of a loose list:

 *  This text is a paragraph, and so will be separated from the other items
    by a longer vertical space.

 *  That is good because it improves readability both in the rendered form
    as well as in the text form.

 *  And we care about the readability of our texts and encourage people to
    write them better.
    The tight list of valid values:

 *  6;
 *  24;
 *  72.

  • § Prefer triple-backtick fenced code blocks with language tags as info strings to indented code blocks and fenced code blocks without info strings. If the code block must contain a triple-backtick itself, use triple-tilde fenced code blocks instead.

  • § Provide a table of contents for large documents.

  • § Put punctuation inside the text in bold and italic:

    This is **very important!**  You need to use *these;* those won't work.

  • § Use asterisks and not underscores for bold and italic.

  • § Use both id and the deprecated name attributes to make it work in Markdown renderers that strip ids.

  • § Use either link references or link destinations only, unless making a table of contents. Put all link reference definitions at the end of the second-level section or, if the second-level section is large, at the end of a third-level one.

  • § Use none as the info string for plain text or custom formats, such as adblock rules.

  • §

    [!WARNING]

    This rule is obsoleted by the rule about names.

    Use the IDs that GitHub would generate in order for this to work both on GitHub and most other Markdown renderers.

  • §

    [!WARNING]

    This rule is deprecated. See message at the beginning of the document.

    When a code block interrupts a flow of a sentence, the line following the code block should start with a small letter.

    For example, the following line of code:

```c
printf("hello from process #%d\n", procnum);
```

will print `hello from process #42`.