1# Markdown style guide 2 3Much of what makes Markdown great is the ability to write plain text, and get 4great formatted output as a result. To keep the slate clean for the next author, 5your Markdown should be simple and consistent with the whole corpus wherever 6possible. 7 8We seek to balance three goals: 9 101. *Source text is readable and portable.* 112. *Markdown files are maintainable over time and across teams.* 123. *The syntax is simple and easy to remember.* 13 14Contents: 15 161. [Document layout](#document-layout) 171. [Character line limit](#character-line-limit) 181. [Trailing whitespace](#trailing-whitespace) 191. [Headings](#headings) 20 1. [ATX-style headings](#atx-style-headings) 21 1. [Add spacing to headings](#add-spacing-to-headings) 221. [Lists](#lists) 23 1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists) 24 1. [Nested list spacing](#nested-list-spacing) 251. [Code](#code) 26 1. [Inline](#inline) 27 1. [Codeblocks](#codeblocks) 28 1. [Declare the language](#declare-the-language) 29 1. [Escape newlines](#escape-newlines) 30 1. [Nest codeblocks within lists](#nest-codeblocks-within-lists) 311. [Links](#links) 32 1. [Use informative Markdown link titles](#use-informative-markdown-link-titles) 331. [Images](#images) 341. [Prefer lists to tables](#prefer-lists-to-tables) 351. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html) 36 37## Document layout 38 39In general, most documents benefit from some variation of the following layout: 40 41```markdown 42# Document Title 43 44Short introduction. 45 46[TOC] 47 48## Topic 49 50Content. 51 52## See also 53 54* https://link-to-more-info 55``` 56 571. `# Document Title`: The first heading should be a level one heading, and 58 should ideally be the same or nearly the same as the filename. The first 59 level one heading is used as the page `<title>`. 60 611. `author`: *Optional*. If you'd like to claim ownership of the document or 62 if you are very proud of it, add yourself under the title. However, 63 revision history generally suffices. 64 651. `Short introduction.` 1-3 sentences providing a high-level overview of the 66 topic. Imagine yourself as a complete newbie, who landed on your "Extending 67 Foo" doc and needs to know the most basic assumptions you take for granted. 68 "What is Foo? Why would I extend it?" 69 701. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles, 71 put `[TOC]` after the short introduction. See 72 [`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents). 73 741. `## Topic`: The rest of your headings should start from level 2. 75 761. `## See also`: Put miscellaneous links at the bottom for the user who wants 77 to know more or didn't find what she needed. 78 79## Character line limit 80 81Obey projects' character line limit wherever possible. Long URLs and tables are 82the usual suspects when breaking the rule. (Headings also can't be wrapped, but 83we encourage keeping them short). Otherwise, wrap your text: 84 85```markdown 86Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo 87hendrerit, id nobis saperet fuisset ius. 88 89* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur 90 interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md). 91``` 92 93Often, inserting a newline before a long link preserves readability while 94minimizing the overflow: 95 96```markdown 97Lorem ipsum dolor sit amet. See the 98[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md) 99for details. 100``` 101 102## Trailing whitespace 103 104Don't use trailing whitespace, use a trailing backslash. 105 106The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees 107that two spaces at the end of a line should insert a `<br />` tag. However, many 108directories have a trailing whitespace presubmit check in place, and many IDEs 109will clean it up anyway. 110 111Best practice is to avoid the need for a `<br />` altogether. Markdown creates 112paragraph tags for you simply with newlines: get used to that. 113 114## Headings 115 116### ATX-style headings 117 118```markdown 119## Heading 2 120``` 121 122Headings with `=` or `-` underlines can be annoying to maintain and don't fit 123with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or 124H2? 125 126```markdown 127Heading - do you remember what level? DO NOT DO THIS. 128--------- 129``` 130 131### Add spacing to headings 132 133Prefer spacing after `#` and newlines before and after: 134 135```markdown 136...text before. 137 138# Heading 1 139 140Text after... 141``` 142 143Lack of spacing makes it a little harder to read in source: 144 145```markdown 146...text before. 147 148#Heading 1 149Text after... DO NOT DO THIS. 150``` 151 152## Lists 153 154### Use lazy numbering for long lists 155 156Markdown is smart enough to let the resulting HTML render your numbered lists 157correctly. For longer lists that may change, especially long nested lists, use 158"lazy" numbering: 159 160```markdown 1611. Foo. 1621. Bar. 163 1. Foofoo. 164 1. Barbar. 1651. Baz. 166``` 167 168However, if the list is small and you don't anticipate changing it, prefer fully 169numbered lists, because it's nicer to read in source: 170 171```markdown 1721. Foo. 1732. Bar. 1743. Baz. 175``` 176 177### Nested list spacing 178 179When nesting lists, use a 4 space indent for both numbered and bulleted lists: 180 181```markdown 1821. 2 spaces after a numbered list. 183 4 space indent for wrapped text. 1842. 2 spaces again. 185 186* 3 spaces after a bullet. 187 4 space indent for wrapped text. 188 1. 2 spaces after a numbered list. 189 8 space indent for the wrapped text of a nested list. 190 2. Looks nice, don't it? 191* 3 spaces after a bullet. 192``` 193 194The following works, but it's very messy: 195 196```markdown 197* One space, 198with no indent for wrapped text. 199 1. Irregular nesting... DO NOT DO THIS. 200``` 201 202Even when there's no nesting, using the 4 space indent makes layout consistent 203for wrapped text: 204 205```markdown 206* Foo, 207 wrapped. 208 2091. 2 spaces 210 and 4 space indenting. 2112. 2 spaces again. 212``` 213 214However, when lists are small, not nested, and a single line, one space can 215suffice for both kinds of lists: 216 217```markdown 218* Foo 219* Bar 220* Baz. 221 2221. Foo. 2232. Bar. 224``` 225 226## Code 227 228### Inline 229 230`Backticks` designate `inline code`, and will render all wrapped content 231literally. Use them for short code quotations and field names: 232 233```markdown 234You'll want to run `really_cool_script.sh arg`. 235 236Pay attention to the `foo_bar_whammy` field in that table. 237``` 238 239Use inline code when referring to file types in an abstract sense, rather than a 240specific file: 241 242```markdown 243Be sure to update your `README.md`! 244``` 245 246Backticks are the most common approach for "escaping" Markdown metacharacters; 247in most situations where escaping would be needed, code font just makes sense 248anyway. 249 250### Codeblocks 251 252For code quotations longer than a single line, use a codeblock: 253 254<pre> 255```python 256def Foo(self, bar): 257 self.bar = bar 258``` 259</pre> 260 261#### Declare the language 262 263It is best practice to explicitly declare the language, so that neither the 264syntax highlighter nor the next editor must guess. 265 266#### Indented codeblocks are sometimes cleaner 267 268Four-space indenting is also interpreted as a codeblock. These can look 269cleaner and be easier to read in source, but there is no way to specify the 270language. We encourage their use when writing many short snippets: 271 272```markdown 273You'll need to run: 274 275 bazel run :thing -- --foo 276 277And then: 278 279 bazel run :another_thing -- --bar 280 281And again: 282 283 bazel run :yet_again -- --baz 284``` 285 286#### Escape newlines 287 288Because most commandline snippets are intended to be copied and pasted directly 289into a terminal, it's best practice to escape any newlines. Use a single 290backslash at the end of the line: 291 292<pre> 293```shell 294bazel run :target -- --flag --foo=longlonglonglonglongvalue \ 295--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue 296``` 297</pre> 298 299#### Nest codeblocks within lists 300 301If you need a codeblock within a list, make sure to indent it so as to not break 302the list: 303 304```markdown 305* Bullet. 306 307 ```c++ 308 int foo; 309 ``` 310 311* Next bullet. 312``` 313 314You can also create a nested code block with 4 spaces. Simply indent 4 315additional spaces from the list indentation: 316 317```markdown 318* Bullet. 319 320 int foo; 321 322* Next bullet. 323``` 324 325## Links 326 327Long links make source Markdown difficult to read and break the 80 character 328wrapping. **Wherever possible, shorten your links**. 329 330### Use informative Markdown link titles 331 332Markdown link syntax allows you to set a link title, just as HTML does. Use it 333wisely. 334 335Titling your links as "link" or "here" tells the reader precisely nothing when 336quickly scanning your doc and is a waste of space: 337 338```markdown 339See the syntax guide for more info: [link](syntax_guide.md). 340Or, check out the style guide [here](style_guide.md). 341DO NOT DO THIS. 342``` 343 344Instead, write the sentence naturally, then go back and wrap the most 345appropriate phrase with the link: 346 347```markdown 348See the [syntax guide](syntax_guide.md) for more info. 349Or, check out the [style guide](style_guide.md). 350``` 351 352## Images 353 354Use images sparingly, and prefer simple screenshots. This guide is designed 355around the idea that plain text gets users down to the business of communication 356faster with less reader distraction and author procrastination. However, it's 357sometimes very helpful to show what you mean. 358 359See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images). 360 361## Prefer lists to tables 362 363Any tables in your Markdown should be small. Complex, large tables are difficult 364to read in source and most importantly, **a pain to modify later**. 365 366```markdown 367Fruit | Attribute | Notes 368--- | --- | --- | --- 369Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away. 370Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes. 371 372DO NOT DO THIS 373``` 374 375[Lists](#lists) and subheadings usually suffice to present the same information 376in a slightly less compact, though much more edit-friendly way: 377 378```markdown 379## Fruits 380 381### Apple 382 383* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL) 384* Firm 385* Sweet 386 387Apples keep doctors away. 388 389### Banana 390 391* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery) 392* Soft 393* Sweet 394 395Contrary to popular belief, most apes prefer mangoes. 396``` 397 398However, there are times when a small table is called for: 399 400```markdown 401Transport | Favored by | Advantages 402--- | --- | --- 403Swallow | Coconuts | Otherwise unladen 404Bicycle | Miss Gulch | Weatherproof 405X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out 406``` 407 408## Strongly prefer Markdown to HTML 409 410Please prefer standard Markdown syntax wherever possible and avoid HTML hacks. 411If you can't seem to accomplish what you want, reconsider whether you really 412need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost 413all needs already. 414 415Every bit of HTML or Javascript hacking reduces the readability and portability. 416This in turn limits the usefulness of integrations with 417other tools, which may either present the source as plain text or render it. See 418[Philosophy](philosophy.md). 419 420Gitiles does not render HTML. 421