You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/developers/website.markdown
+51-12Lines changed: 51 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -13,39 +13,78 @@ The website you're reading now is the home of Home Assistant: [https://home-assi
13
13
14
14
home-assistant.io is built using [Jekyll](http://github.com/mojombo/jekyll). The pages are written in [markdown](http://daringfireball.net/projects/markdown/); to add a page you don't need to know about HTML or the like.
15
15
16
-
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.
16
+
The link "**Edit this page on GitHub**" allows one to edit pages without creating a fork.
17
+
18
+
For larger changes, we suggest that you clone the website repository. This has the advantage that 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.
17
19
18
20
To test your changes locally, you need to install the **Ruby** dependencies (gems):
19
21
20
22
-[Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already.
21
23
- Install `bundler`, which is a dependency manager for Ruby: `gem install bundler`
22
-
- In your home-assistant.io root directory, run `bundle` to install the gems you need.
24
+
- In your home-assistant.github.io root directory, run `bundle` to install the gems you need.
- Create/edit/update a page in the directory `source/_components/` for your platform/component.
28
-
- Test your changes to home-assistant.io locally: run ``rake preview`` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000)
29
-
- Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is for a new feature, platform, or component.
30
-
- Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
30
+
- Test your changes to home-assistant.io locally: run `rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000)
31
+
- Create a Pull Request (PR) against the **next** branch of home-assistant.github.io if your documentation is for a new feature, platform, or component.
32
+
- 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.
33
+
34
+
35
+
### {% linkable_title Create a page %}
36
+
37
+
For a platform 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.
31
38
32
-
For a platform page, the fastest way is to make a copy of an existing page and edit it. The [component overview](/components/) is generated automatically, so there is no need to add a link to your page.
39
+
If you start from scratch with a page, you need to add a header. Different sections of the doumentation may need different headers.
40
+
41
+
```text
42
+
---
43
+
layout: page
44
+
title: "Website home-assistant.io"
45
+
description: "home-assistant.io web presence"
46
+
date: 2015-06-17 08:00
47
+
sidebar: true
48
+
comments: false
49
+
sharing: true
50
+
footer: true
51
+
---
52
+
53
+
Content...Written in markdown.
54
+
55
+
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
56
+
...
57
+
```
58
+
59
+
There are [pre-definied variables](https://jekyllrb.com/docs/variables/) available but usually it's not necessary to use them when writing documentation.
33
60
34
61
### {% linkable_title Embedding Code %}
35
62
36
-
You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in \`. For multi line syntax wrap your code like this:
63
+
You can use the default markdown syntax to generate syntax highlighted code. For inline code wrap your code in \`. For multi line syntax wrap your code as shown below.
37
64
38
65
```text
39
-
\`\`\`yaml
40
-
sensor:
41
-
platform: template
42
-
\`\`\`
66
+
{% raw %} ```yaml
67
+
sensor:
68
+
platform: template
69
+
```{% endraw %}
43
70
```
44
71
45
-
Note that you can replace `text` next to \`\`\` with the language that is within the block.
72
+
If you are using templates then those parts needs to be [escaped](http://stackoverflow.com/a/24102537). Otherwise they will be rendered and appear blank on the website.
73
+
74
+
Note that you can replace `yaml` next to \`\`\` with the language that is within the block.
46
75
47
76
When you're writing code that is to be executed on the terminal, prefix it with `$`.
48
77
78
+
### {% linkable_title HTML %}
79
+
80
+
The direct usage of HTML is supported but not recommanded. The note boxes are an exception.
81
+
82
+
```html
83
+
<pclass='note warning'>
84
+
You need to enable telnet on your router.
85
+
</p>
86
+
```
87
+
49
88
### {% linkable_title Images, icons, and logos %}
50
89
51
90
The images which are displayed on the pages are stored in various directories according to their purpose.
0 commit comments