Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 1 | Markdown |
| 2 | ======== |
| 3 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 4 | This site can handle normal Markdown and many common extensions. To learn |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 5 | how the following is done please see the [source for this page](./markdown.md). |
| 6 | Any file you put under `/site/` that has the extension `.md` will be processed |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 7 | as Markdown. All other files will be served directly. For example, images |
| 8 | can be added and they will be served correctly and referenced from within Markdown files. |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 9 | |
| 10 | When preparing for a code review of site docs you can get a preview of how the |
| 11 | page will render by visiting the skia.org site and add a query parameter `cl` |
| 12 | with the value of the Reitveld issue id: |
| 13 | |
| 14 | https://skia.org/path/to/markdown-file?cl=REITVELD_ISSUE_NUMBER |
| 15 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 16 | This is the preferred method of previewing docs changes. |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 17 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 18 | If for some reason you can't use the method above to preview docs changes you |
| 19 | can also run a local copy of the documentation server, which will allow you to |
| 20 | preview changes much quicker. You must have a recent version (>=8.9) of |
| 21 | [node](https://nodejs.org/) installed on your machine. You must also have |
| 22 | [Go](https://golang.org) installed on your computer, which you will have if |
| 23 | you are running on a Google corporate workstation. Installation also means |
| 24 | that you have `$GOPATH/bin` [added to your PATH](https://golang.org/doc/code.html#GOPATH). Run: |
| 25 | |
| 26 | go get -u go.skia.org/infra/doc/go/docserver |
| 27 | cd $GOPATH/src/go.skia.org/infra/doc |
| 28 | make |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 29 | |
| 30 | And then **from within** the directory of your local Git checkout of Skia run: |
| 31 | |
| 32 | docserver --preview --local |
| 33 | |
| 34 | Then visit http://localhost:8000 to preview your changes. There is no need to |
| 35 | restart the server for file changes, but you will need to restart it if there |
| 36 | are changes to the navigation menu, i.e. you add or remove a file and want it |
| 37 | to appear in the navigation on the right hand side of the page. |
| 38 | |
| 39 | If port 8000 is unavailable on your machine you can set the port to use via |
| 40 | the --port flag: |
| 41 | |
| 42 | docserver --preview --local --port=:8002 |
| 43 | |
| 44 | METADATA |
| 45 | -------- |
| 46 | |
| 47 | By default all files and directories that appear in the same level are sorted |
| 48 | alphabetically by file name in the navigation menu, with files appearing |
| 49 | before directories. You can override this default behavior by adding a |
| 50 | METADATA file to a directory. A METADATA file is a JSON file of the following |
| 51 | format: |
| 52 | |
| 53 | ~~~~ |
| 54 | { |
| 55 | "dirOrder": ["sample", "quick", "special"], |
| 56 | "fileOrder": ["download", "api"] |
| 57 | } |
| 58 | ~~~~ |
| 59 | |
| 60 | If a file or directory doesn't appear in `dirOrder` or `fileOrder` then it is sorted |
| 61 | to appear after the members of `dirOrder` or `fileOrder` respectively. All |
| 62 | files and directories that aren't controlled by a METADATA file are sorted in |
| 63 | alphabetical order by their filename. |
| 64 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 65 | Some Example Markdown |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 66 | --------------------- |
| 67 | |
| 68 | This is a [link](https://www.google.com). You can also create |
| 69 | ordered and unordered lists: |
| 70 | |
| 71 | 1. First |
| 72 | 2. Second: |
| 73 | * Fee |
| 74 | * Fie |
| 75 | * Foe |
| 76 | * Fum |
| 77 | 3. Third |
| 78 | |
| 79 | Incorporate images: |
| 80 | |
| 81 | ![image](/dev/tools/image.png) |
| 82 | |
| 83 | Or go old school and use [ASCII art](http://asciiflow.com/): |
| 84 | |
| 85 | ~~~~ |
| 86 | |
| 87 | +----------------+ |
| 88 | | Should you | |
| 89 | +--+ use ASCII art? +--+ |
| 90 | | +----------------+ | |
| 91 | | | |
| 92 | +---v---+ +---v---+ |
| 93 | | | | | |
| 94 | | Yes | | No | |
| 95 | | | | | |
| 96 | +-------+ +-------+ |
| 97 | |
| 98 | ~~~~ |
| 99 | |
| 100 | Format code snippets or other preformatted text. Just surround the code |
| 101 | with `~~~~`. You can also trigger syntax highlighting by putting in |
| 102 | the following HTML comment before the code section: |
| 103 | |
| 104 | <!--?prettify?--> |
| 105 | |
| 106 | |
| 107 | <!--?prettify?--> |
| 108 | ~~~~ |
| 109 | class SK_API SkPaint { |
| 110 | public: |
| 111 | SkPaint(); |
| 112 | SkPaint(const SkPaint& paint); |
| 113 | ~SkPaint(); |
| 114 | |
| 115 | SkPaint& operator=(const SkPaint&); |
| 116 | ~~~~ |
| 117 | |
| 118 | |
| 119 | Tables |
| 120 | |
| 121 | Name | Value | Summary |
| 122 | --------|----------|-------- |
| 123 | A | 27 | yes |
| 124 | B | 23 | no |
| 125 | |
| 126 | |
| 127 | There are also inline styles for *emphasis*, **bold**, |
| 128 | ~~strikethrough~~, and `inline code`. Also small fractions, |
| 129 | such as 1/2 are rendered nicely. |
| 130 | |
| 131 | > # There are |
| 132 | > ## Headers |
| 133 | > ### Up To |
| 134 | > #### Six |
| 135 | > ##### Levels |
| 136 | > ###### Deep |
| 137 | |
| 138 | And you can <b>always</b> use HTML, which is useful for features that can't be |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 139 | done in Markdown, such as iframes, but try to avoid using HTML outside of |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 140 | sitations like that. |
| 141 | <svg viewBox="0 0 24 24" height="24px" width="24px" style="display: inline;"> |
| 142 | <g> |
| 143 | <path d="M1 |
| 144 | 21h4v-12h-4v12zm22-11c0-1.1-.9-2-2-2h-6.31l.95-4.57.03-.32c0-.41-.17-.79-.44-1.06l-1.06-1.05-6.58 |
| 145 | 6.59c-.37.36-.59.86-.59 1.41v10c0 1.1.9 2 2 2h9c.83 0 1.54-.5 |
| 146 | 1.84-1.22l3.02-7.05c.09-.23.14-.47.14-.73v-1.91l-.01-.01.01-.08z"> </path> |
| 147 | </g> |
| 148 | </svg> |
| 149 | |
| 150 | Reference |
| 151 | ========= |
| 152 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 153 | Below is a longer reference on the Markdown that docserver accepts. |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 154 | |
| 155 | Paragraphs |
| 156 | ---------- |
| 157 | |
| 158 | A paragraph is simply one or more consecutive lines of text, separated |
| 159 | by one or more blank lines. (A blank line is any line that looks like a |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 160 | blank line -- a line containing nothing. Note: all spaces or tabs is considered |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 161 | blank.) Normal paragraphs should not be intended with spaces or tabs. |
| 162 | |
| 163 | Headers and Blockquotes |
| 164 | ----------------------- |
| 165 | |
| 166 | You can create headers by either "underlining" with equal signs (`=`) and hyphens (`-`), |
| 167 | or,you can put 1-6 hash marks (`#`) at the |
| 168 | beginning of the line -- the number of hashes equals the resulting |
| 169 | HTML header level. |
| 170 | |
| 171 | Blockquotes are indicated using email-style '`>`' angle brackets. |
| 172 | |
| 173 | Markdown: |
| 174 | |
| 175 | A First Level Header |
| 176 | ==================== |
| 177 | |
| 178 | A Second Level Header |
| 179 | --------------------- |
| 180 | |
| 181 | Now is the time for all good men to come to |
| 182 | the aid of their country. This is just a |
| 183 | regular paragraph. |
| 184 | |
| 185 | The quick brown fox jumped over the lazy |
| 186 | dog's back. |
| 187 | |
| 188 | ### Header 3 |
| 189 | |
| 190 | > This is a blockquote. |
| 191 | > |
| 192 | > This is the second paragraph in the blockquote. |
| 193 | > |
| 194 | > ## This is an H2 in a blockquote |
| 195 | |
| 196 | |
| 197 | Output: |
| 198 | |
| 199 | <h1>A First Level Header</h1> |
| 200 | |
| 201 | <h2>A Second Level Header</h2> |
| 202 | |
| 203 | <p>Now is the time for all good men to come to |
| 204 | the aid of their country. This is just a |
| 205 | regular paragraph.</p> |
| 206 | |
| 207 | <p>The quick brown fox jumped over the lazy |
| 208 | dog's back.</p> |
| 209 | |
| 210 | <h3>Header 3</h3> |
| 211 | |
| 212 | <blockquote> |
| 213 | <p>This is a blockquote.</p> |
| 214 | |
| 215 | <p>This is the second paragraph in the blockquote.</p> |
| 216 | |
| 217 | <h2>This is an H2 in a blockquote</h2> |
| 218 | </blockquote> |
| 219 | |
| 220 | |
| 221 | |
| 222 | ### Phrase Emphasis ### |
| 223 | |
| 224 | Markdown uses asterisks and underscores to indicate spans of emphasis. |
| 225 | |
| 226 | Markdown: |
| 227 | |
| 228 | Some of these words *are emphasized*. |
| 229 | Some of these words _are emphasized also_. |
| 230 | |
| 231 | Use two asterisks for **strong emphasis**. |
| 232 | Or, if you prefer, __use two underscores instead__. |
| 233 | |
| 234 | Output: |
| 235 | |
| 236 | <p>Some of these words <em>are emphasized</em>. |
| 237 | Some of these words <em>are emphasized also</em>.</p> |
| 238 | |
| 239 | <p>Use two asterisks for <strong>strong emphasis</strong>. |
| 240 | Or, if you prefer, <strong>use two underscores instead</strong>.</p> |
| 241 | |
| 242 | |
| 243 | |
| 244 | ## Lists ## |
| 245 | |
| 246 | Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`, |
| 247 | `+`, and `-`) as list markers. These three markers are |
| 248 | interchangable; this: |
| 249 | |
| 250 | * Candy. |
| 251 | * Gum. |
| 252 | * Booze. |
| 253 | |
| 254 | this: |
| 255 | |
| 256 | + Candy. |
| 257 | + Gum. |
| 258 | + Booze. |
| 259 | |
| 260 | and this: |
| 261 | |
| 262 | - Candy. |
| 263 | - Gum. |
| 264 | - Booze. |
| 265 | |
| 266 | all produce the same output: |
| 267 | |
| 268 | <ul> |
| 269 | <li>Candy.</li> |
| 270 | <li>Gum.</li> |
| 271 | <li>Booze.</li> |
| 272 | </ul> |
| 273 | |
| 274 | Ordered (numbered) lists use regular numbers, followed by periods, as |
| 275 | list markers: |
| 276 | |
| 277 | 1. Red |
| 278 | 2. Green |
| 279 | 3. Blue |
| 280 | |
| 281 | Output: |
| 282 | |
| 283 | <ol> |
| 284 | <li>Red</li> |
| 285 | <li>Green</li> |
| 286 | <li>Blue</li> |
| 287 | </ol> |
| 288 | |
| 289 | If you put blank lines between items, you'll get `<p>` tags for the |
| 290 | list item text. You can create multi-paragraph list items by indenting |
| 291 | the paragraphs by 4 spaces or 1 tab: |
| 292 | |
| 293 | * A list item. |
| 294 | |
| 295 | With multiple paragraphs. |
| 296 | |
| 297 | * Another item in the list. |
| 298 | |
| 299 | Output: |
| 300 | |
| 301 | <ul> |
| 302 | <li><p>A list item.</p> |
| 303 | <p>With multiple paragraphs.</p></li> |
| 304 | <li><p>Another item in the list.</p></li> |
| 305 | </ul> |
| 306 | |
| 307 | |
| 308 | |
| 309 | ### Links ### |
| 310 | |
| 311 | Markdown supports two styles for creating links: *inline* and |
| 312 | *reference*. With both styles, you use square brackets to delimit the |
| 313 | text you want to turn into a link. |
| 314 | |
| 315 | Inline-style links use parentheses immediately after the link text. |
| 316 | For example: |
| 317 | |
| 318 | This is an [example link](http://example.com/). |
| 319 | |
| 320 | Output: |
| 321 | |
| 322 | <p>This is an <a href="http://example.com/"> |
| 323 | example link</a>.</p> |
| 324 | |
| 325 | Optionally, you may include a title attribute in the parentheses: |
| 326 | |
| 327 | This is an [example link](http://example.com/ "With a Title"). |
| 328 | |
| 329 | Output: |
| 330 | |
| 331 | <p>This is an <a href="http://example.com/" title="With a Title"> |
| 332 | example link</a>.</p> |
| 333 | |
| 334 | Reference-style links allow you to refer to your links by names, which |
| 335 | you define elsewhere in your document: |
| 336 | |
| 337 | I get 10 times more traffic from [Google][1] than from |
| 338 | [Yahoo][2] or [MSN][3]. |
| 339 | |
| 340 | [1]: http://google.com/ "Google" |
| 341 | [2]: http://search.yahoo.com/ "Yahoo Search" |
| 342 | [3]: http://search.msn.com/ "MSN Search" |
| 343 | |
| 344 | Output: |
| 345 | |
| 346 | <p>I get 10 times more traffic from <a href="http://google.com/" |
| 347 | title="Google">Google</a> than from <a href="http://search.yahoo.com/" |
| 348 | title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/" |
| 349 | title="MSN Search">MSN</a>.</p> |
| 350 | |
| 351 | The title attribute is optional. Link names may contain letters, |
| 352 | numbers and spaces, but are *not* case sensitive: |
| 353 | |
| 354 | I start my morning with a cup of coffee and |
| 355 | [The New York Times][NY Times]. |
| 356 | |
| 357 | [ny times]: http://www.nytimes.com/ |
| 358 | |
| 359 | Output: |
| 360 | |
| 361 | <p>I start my morning with a cup of coffee and |
| 362 | <a href="http://www.nytimes.com/">The New York Times</a>.</p> |
| 363 | |
| 364 | |
| 365 | ### Images ### |
| 366 | |
| 367 | Image syntax is very much like link syntax. |
| 368 | |
| 369 | Inline (titles are optional): |
| 370 | |
| 371 | ![alt text](/path/to/img.jpg "Title") |
| 372 | |
| 373 | Reference-style: |
| 374 | |
| 375 | ![alt text][id] |
| 376 | |
| 377 | [id]: /path/to/img.jpg "Title" |
| 378 | |
| 379 | Both of the above examples produce the same output: |
| 380 | |
| 381 | <img src="/path/to/img.jpg" alt="alt text" title="Title" /> |
| 382 | |
| 383 | |
| 384 | |
| 385 | ### Code ### |
| 386 | |
| 387 | In a regular paragraph, you can create code span by wrapping text in |
| 388 | backtick quotes. Any ampersands (`&`) and angle brackets (`<` or |
| 389 | `>`) will automatically be translated into HTML entities. This makes |
| 390 | it easy to use Markdown to write about HTML example code: |
| 391 | |
| 392 | I strongly recommend against using any `<blink>` tags. |
| 393 | |
| 394 | I wish SmartyPants used named entities like `—` |
| 395 | instead of decimal-encoded entites like `—`. |
| 396 | |
| 397 | Output: |
| 398 | |
| 399 | <p>I strongly recommend against using any |
| 400 | <code><blink></code> tags.</p> |
| 401 | |
| 402 | <p>I wish SmartyPants used named entities like |
| 403 | <code>&mdash;</code> instead of decimal-encoded |
| 404 | entites like <code>&#8212;</code>.</p> |
| 405 | |
| 406 | |
| 407 | To specify an entire block of pre-formatted code, indent every line of |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 408 | the block by 4 spaces or 1 tab, or add a line containing three backticks before |
| 409 | and after the code block. Just like with code spans, `&`, `<`, |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 410 | and `>` characters will be escaped automatically. |
| 411 | |
| 412 | Markdown: |
| 413 | |
| 414 | If you want your page to validate under XHTML 1.0 Strict, |
| 415 | you've got to put paragraph tags in your blockquotes: |
| 416 | |
| 417 | <blockquote> |
| 418 | <p>For example.</p> |
| 419 | </blockquote> |
| 420 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 421 | or |
| 422 | |
| 423 | If you want your page to validate under XHTML 1.0 Strict, |
| 424 | you've got to put paragraph tags in your blockquotes: |
| 425 | |
| 426 | ``` |
| 427 | <blockquote> |
| 428 | <p>For example.</p> |
| 429 | </blockquote> |
| 430 | ``` |
| 431 | |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 432 | Output: |
| 433 | |
| 434 | <p>If you want your page to validate under XHTML 1.0 Strict, |
| 435 | you've got to put paragraph tags in your blockquotes:</p> |
| 436 | |
| 437 | <pre><code><blockquote> |
| 438 | <p>For example.</p> |
| 439 | </blockquote> |
| 440 | </code></pre> |
| 441 | |
Xiaoming Shi | 73dfa20 | 2020-03-12 11:31:35 -0700 | [diff] [blame] | 442 | |
Andrew Top | 200ce4b | 2018-01-29 13:43:50 -0800 | [diff] [blame] | 443 | ### Floating Menu ### |
| 444 | |
| 445 | To create a floating menu for a single page that always appears |
| 446 | in the upper right hand corner of the page, use a `div` with a |
| 447 | class of "float", for example: |
| 448 | |
| 449 | <div class="float"> |
| 450 | <ul> |
| 451 | <li><a href="#SkXfermode">SkXfermode</a></li> |
| 452 | <li><a href="#SkShader">SkShader</a></li> |
| 453 | <li><a href="#SkMaskFilter">SkMaskFilter</a></li> |
| 454 | <li><a href="#SkColorFilter">SkColorFilter</a></li> |
| 455 | <li><a href="#SkPathEffect">SkPathEffect</a></li> |
| 456 | </ul> |
| 457 | </div> |
| 458 | |