|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: "Create a new page" |
| 4 | +description: "Create a new page for the documentation" |
| 5 | +date: 2015-06-17 08:00 |
| 6 | +sidebar: true |
| 7 | +comments: false |
| 8 | +sharing: true |
| 9 | +footer: true |
| 10 | +--- |
| 11 | + |
| 12 | +For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](/components/) and the [Examples section](/cookbook/) are generated automatically, so there is no need to add a link to those pages. |
| 13 | + |
| 14 | +Please honor the Standards we have for the documentation. |
| 15 | + |
| 16 | +If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers. |
| 17 | + |
| 18 | +```text |
| 19 | +--- |
| 20 | +layout: page |
| 21 | +title: "Awesome Sensor" |
| 22 | +description: "home-assistant.io web presence" |
| 23 | +date: 2015-06-17 08:00 |
| 24 | +sidebar: true |
| 25 | +comments: false |
| 26 | +sharing: true |
| 27 | +footer: true |
| 28 | +ha_release: "0.38" |
| 29 | +ha_category: Sensor |
| 30 | +--- |
| 31 | +
|
| 32 | +Content...Written in markdown. |
| 33 | +
|
| 34 | +{% raw %}### {% linkable_title Linkable Header %}{% endraw %} |
| 35 | +... |
| 36 | +``` |
| 37 | + |
| 38 | +There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually, it's not necessary to use them when writing documentation. |
| 39 | + |
| 40 | +A couple of points to remember: |
| 41 | + |
| 42 | +- Document the needed steps to retrieve API keys or access token for the third party service or device if needed. |
| 43 | +- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`. |
| 44 | +- `ha_category:` is needed to list the platform or component in the appropriate category on the website. |
| 45 | + |
| 46 | +### {% linkable_title Configuration %} |
| 47 | + |
| 48 | +Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file. |
| 49 | + |
| 50 | +The **Configuration Variables** section must use the {% raw %}`{% configuration %} ... {% endconfiguration %}`{% endraw %} tag. |
| 51 | + |
| 52 | + |
| 53 | +```text |
| 54 | +{% raw %} |
| 55 | +{% configuration %} |
| 56 | + api_key: |
| 57 | + description: The API key to access the service. |
| 58 | + required: true |
| 59 | + type: string |
| 60 | + name: |
| 61 | + description: Name to use in the frontend. |
| 62 | + required: false |
| 63 | + type: string |
| 64 | +{% endconfiguration %} |
| 65 | +{% endraw %} |
| 66 | +``` |
| 67 | + |
| 68 | +- **`description:`**: That the variable is about. |
| 69 | +- **`required:`**: If the variable is required. |
| 70 | +```text |
| 71 | +required: true #=> Required |
| 72 | +required: false #=> Optional |
| 73 | +required: inclusive #=> Inclusive |
| 74 | +required: exclusive #=> Exclusive |
| 75 | +required: any string here #=> Any string here |
| 76 | +``` |
| 77 | +- **`type:`**: The type of the variable. Allowed entries: `string`, `int` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example). |
| 78 | + |
| 79 | +### {% linkable_title Embedding Code %} |
| 80 | + |
| 81 | +You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}. |
| 82 | + |
| 83 | +When you're writing code that is to be executed on the terminal, prefix it with `$`. |
| 84 | + |
| 85 | +### {% linkable_title Templates %} |
| 86 | + |
| 87 | +For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the Documentation Standards for further details. |
| 88 | + |
| 89 | +If you are don't escape templates then they will be rendered and appear blank on the website. |
| 90 | + |
| 91 | +### {% linkable_title HTML %} |
| 92 | + |
| 93 | +The direct usage of HTML is supported but not recommended. The note boxes are an exception. |
| 94 | + |
| 95 | +```html |
| 96 | +<p class='note warning'> |
| 97 | + You need to enable telnet on your router. |
| 98 | +</p> |
| 99 | +``` |
| 100 | + |
| 101 | +### {% linkable_title Redirects %} |
| 102 | +If you rename or move an existing platform or component, create the redirect. Add the old location of the page to the header of the new one. |
| 103 | + |
| 104 | +```text |
| 105 | +--- |
| 106 | +... |
| 107 | +redirect_from: /getting-started/android/ |
| 108 | +--- |
| 109 | +``` |
| 110 | + |
| 111 | +### {% linkable_title Images, icons, and logos %} |
| 112 | + |
| 113 | +The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent. |
| 114 | + |
| 115 | +| Type | Location | |
| 116 | +| :----------- |:----------------------------------------------| |
| 117 | +| logos | source/images/supported_brands | |
| 118 | +| blog | source/images/blog | |
| 119 | +| screenshots | source/images/components | |
| 120 | + |
| 121 | +Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/). |
0 commit comments