- Website home-assistant.io + Create a new page
-
The website you are reading now is the home of Home Assistant: https://home-assistant.io. This is the place where we provide documentation and additional details about Home Assistant for end users and developers.
-home-assistant.io is built using Jekyll and these available dependencies. The pages are written in markdown. To add a page, you don’t need to know about HTML.
-You can use the “Edit this page on GitHub” link to edit pages without creating a fork. Keep in mind that you can’t upload images while working this way.
-For larger changes, we suggest that you clone the website repository. This way, you can review your changes locally. The process for working on the website is no different from working on Home Assistant itself. You work on your change and propose it via a pull request.
-To test your changes locally, you need to install Ruby and its dependencies (gems):
--
-
- Install Ruby if you don’t have it already. -
- Install
bundler, a dependency manager for Ruby:$ gem install bundler
- - In your home-assistant.github.io root directory, run
$ bundleto install the gems you need.
-
Short cut for Fedora: $ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle
Then you can work on the documentation:
--
-
- Fork home-assistant.io git repository. -
- Create/edit/update a page in the directory
source/_components/for your platform/component.
- - Test your changes to home-assistant.io locally: run
rake previewand navigate to http://127.0.0.1:4000
- - Create a Pull Request (PR) against the next branch of home-assistant.github.io if your documentation is a new feature, platform, or component. -
- Create a Pull Request (PR) against the current branch of home-assistant.github.io if you fix stuff, create Cookbook entries, or expand existing documentation. -
-It could be necessary that you run rake generate prior to rake preview for the very first preview.
-
-Site generated by rake is only available locally. If you are developing on a headless machine use port forwarding:
-ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine
-
Create a page
-For a platform 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.
+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: "Website home-assistant.io"
+title: "Awesome Sensor"
description: "home-assistant.io web presence"
date: 2015-06-17 08:00
sidebar: true
@@ -113,6 +87,7 @@ comments: false
sharing: true
footer: true
ha_release: "0.38"
+ha_category: Sensor
---
Content...Written in markdown.
@@ -125,13 +100,12 @@ Content...Written in markdown.
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.
- - Keep the configuration sample minimal by only adding the
Required options. Full configuration details with further explanations should go into a separate section.
- - The description of all the configuration variables should contains information about the used defaults.
- 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.
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 {% configuration %} ... {% endconfiguration %} tag.
+The Configuration Variables section must use the {% configuration %} ... {% endconfiguration %} tag.
{% configuration %}
api_key:
@@ -163,8 +137,8 @@ required: any string here #=> Any string here
You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in `.
When you’re writing code that is to be executed on the terminal, prefix it with $.
Templates
-For the configuration templating is Jinja used.
-If you are using templates then those parts needs to be escaped. Otherwise they will be rendered and appear blank on the website.
+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.
HTML
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
<p class='note warning'>
@@ -181,7 +155,7 @@ redirect_from: /getting-started/android/
Images, icons, and logos
-The images which are displayed on the pages are stored in various directories according to their purpose.
+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.
@@ -190,23 +164,27 @@ redirect_from: /getting-started/android/
-
- screenshots
- source/images/screenshots
-
logos
source/images/supported_brands
+
+ blog
+ source/images/blog
+
+
+ screenshots
+ source/images/components
+
-Not everything (product, component, etc.) has a logo. To show something for internal parts of Home Assistant we are using the Material Design Icons.
+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.