|
| 1 | +project_path: /web/_project.yaml |
| 2 | +book_path: /web/resources/_book.yaml |
| 3 | +description: This is the page description placed in the head. |
| 4 | + |
| 5 | +{# wf_updated_on: 2017-12-06 #} |
| 6 | +{# wf_published_on: 2016-09-13 #} |
| 7 | +{# wf_blink_components: N/A #} |
| 8 | + |
| 9 | +# Writing an Article {: .page-title } |
| 10 | + |
| 11 | +{% include "web/_shared/contributors/petelepage.html" %} |
| 12 | + |
| 13 | +This is the intro paragraph. It's the equivalent of the old `introduction` |
| 14 | +yaml attribute, but instead of living in the YAML front matter, it now lives |
| 15 | +in the document. |
| 16 | + |
| 17 | +To write a brand new article, follow these steps. Or simply make a copy of |
| 18 | +this markdown file, place it in the directory you want, and edit away. |
| 19 | + |
| 20 | +## YAML Front Matter |
| 21 | + |
| 22 | +All documents need to have a minimum set of YAML front matter including a link |
| 23 | +to the `_project.yaml`, and one to the `_book.yaml`. |
| 24 | + |
| 25 | + project_path: /web/_project.yaml |
| 26 | + book_path: /web/section/_book.yaml |
| 27 | + |
| 28 | +Note: If the path to the project or book cannot be found, the page will not |
| 29 | +include the left nav and the upper tabs will not be properly highlighted. |
| 30 | + |
| 31 | +### Description (optional) |
| 32 | + |
| 33 | +You can provide a page description in the YAML front matter that is used as the |
| 34 | +`meta` description for the page. The description should be short (<450 char), |
| 35 | +and only provide a brief synopsis of the page. |
| 36 | + |
| 37 | + description: Lorem ipsum |
| 38 | + |
| 39 | +Caution: Do not</span> include <code> blocks (or `) in the description field. |
| 40 | + |
| 41 | +### Other YAML Attributes |
| 42 | + |
| 43 | +See [YAML Front Matter and Attribute Reference](/web/resources/yaml-and-attr-reference) |
| 44 | +for all of the YAML Front Matter and other attributes you can or should use. |
| 45 | + |
| 46 | + |
| 47 | +## Page Title (required) |
| 48 | + |
| 49 | +The page title is defined by the first H1-like tag with the `.page-title` class. |
| 50 | +For example: |
| 51 | + |
| 52 | +<pre class="prettyprint"> |
| 53 | +# Writing an Article {: .page-title } |
| 54 | +</pre> |
| 55 | + |
| 56 | +Caution: Page titles should not include any markdown or HTML tags. |
| 57 | + |
| 58 | + |
| 59 | +## Author and Translator Attribution |
| 60 | + |
| 61 | +To include an author or translator attribution, use: |
| 62 | + |
| 63 | +<pre class="prettyprint"> |
| 64 | +{% include "web/_shared/contributors/petelepage.html" %} |
| 65 | +</pre> |
| 66 | + |
| 67 | +## Write Your Content |
| 68 | + |
| 69 | +Next, it's time to add your content. Refer to the [writing style guide](/style/) |
| 70 | +and [markdown syntax](markdown-syntax) guide for full details on the |
| 71 | +styles you can use and how to go about making stuff look pretty. |
| 72 | + |
| 73 | +## Add Article to the Book |
| 74 | + |
| 75 | +To get your article to appear in the appropriate navigation, you need to update |
| 76 | +the `_book.yaml` or `_toc.yaml` file. Each section (updates, shows, fundamentals), |
| 77 | +has it's own `_book.yaml` and which links to individual `_toc.yaml` files. |
| 78 | +You most likely want to add your article to one of the `_toc.yaml` files. |
| 79 | + |
| 80 | +## Test and Submit Your PR |
| 81 | + |
| 82 | +When you're ready, run `gulp test` to make sure that there are no issues with |
| 83 | +your content, then submit your pull request. |
0 commit comments