home-assistant.io/source/developers/documentation/create_page.markdown

layout	title	description	date	sidebar	comments	sharing	footer
page	Create a new page	Create a new page for the documentation	2015-06-17 08:00	true	false	true	true

For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The Component overview and the Examples section are generated automatically, so there is no need to add a link to those pages.

Please honor the Standards we have for the documentation.

If you start from scratch with a page, you need to add a header. Different sections of the documentation may need different headers.

---
layout: page
title: "Awesome Sensor"
description: "home-assistant.io web presence"
date: 2015-06-17 08:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: "0.38"
ha_category: Sensor
---

Content...Written in markdown. 

{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
...

There are pre-definied variables available but usually, it's not necessary to use them when writing documentation.

A couple of points to remember:

• Document the needed steps to retrieve API keys or access token for the third party service or device if needed.
• 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 " ".
• ha_category: is needed to list the platform or component in the appropriate category on the website.

{% linkable_title Configuration %}

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.

The Configuration Variables section must use the {% raw %}{% configuration %} ... {% endconfiguration %}{% endraw %} tag.

{% raw %}
{% configuration %}
  api_key:
    description: The API key to access the service.
    required: true
    type: string
  name:
    description: Name to use in the frontend.
    required: false
    type: string
{% endconfiguration %}
{% endraw %}

• description:: That the variable is about.
• required:: If the variable is required.

required: true            #=> Required
required: false           #=> Optional
required: inclusive       #=> Inclusive
required: exclusive       #=> Exclusive
required: any string here #=> Any string here

• 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 for an example).

{% linkable_title Embedding Code %}

You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}.

When you're writing code that is to be executed on the terminal, prefix it with $.

{% linkable_title Templates %}

For the configuration templating is Jinja used. Check the Documentation Standards for further details.

If you are don't escape templates then they will be rendered and appear blank on the website.

{% linkable_title HTML %}

The direct usage of HTML is supported but not recommended. The note boxes are an exception.

<p class='note warning'>
  You need to enable telnet on your router. 
</p>

{% linkable_title Redirects %}

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.

---
...
redirect_from: /getting-started/android/
---

{% linkable_title Images, icons, and logos %}

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.

Type	Location
logos	source/images/supported_brands
blog	source/images/blog
screenshots	source/images/components

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.