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