Add linkable titles

plugins/linkable_title.rb

@@ -0,0 +1,16 @@
+module Jekyll
+  class LinkableTitleTag < Liquid::Tag
+    def initialize(tag_name, text, token)
+      super
+      @title = text
+    end
+
+    def render(context)
+      slug = @title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '')
+
+      "<a class='title-link' name='#{slug}' href='\##{slug}'></a> #{@title}"
+    end
+  end
+end
+
+Liquid::Template.register_tag('linkable_title', Jekyll::LinkableTitleTag)

sass/custom/_paulus.scss

@@ -2,6 +2,25 @@
 
 // https://fortawesome.github.io/Font-Awesome/3.2.1/icons/
 
+h1:hover a.title-link,
+h2:hover a.title-link,
+h3:hover a.title-link,
+h4:hover a.title-link,
+h5:hover a.title-link,
+h6:hover a.title-link {
+  position: relative;
+
+  &::before {
+    position: absolute;
+    left: -50px;
+    padding-right: 40px;
+    font-family: "FontAwesome";
+    content: "\f0c1"
+  }
+}
+
+f0c1
+
 .ha-title {
   white-space: nowrap;
 

source/developers/add_new_platform.markdown

@@ -26,17 +26,17 @@ Platform logic should not interface directly with the devices but use a third-pa
 </p>
 
 <a name='discovery'></a>
-## Allowing your platform to be discovered
+## {% linkable_title Allowing your platform to be discovered %}
 
 Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event.
 
-### Add discovery instructions
+### {% linkable_title Add discovery instructions %}
 
 Device discovery  for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/balloob/netdisco). This library is integrated using [the `discovery` component](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services.
 
 To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverables.](https://github.com/balloob/netdisco/tree/master/netdisco/discoverables)
 
-### Listening to `SERVICE_DISCOVERED` events
+### {% linkable_title Listening to `SERVICE_DISCOVERED` events %}
 
 From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:
 
@@ -54,7 +54,7 @@ def setup(hass, config):
         hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
 ```
 
-### Auto-loading your component upon discovery
+### {% linkable_title Auto-loading your component upon discovery %}
 
 The Discovery component is capable of setting up your components before firing the `SERVICE_DISCOVERD` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py#L29) constant in [the `discovery` component](https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py).
 

source/developers/api.markdown

@@ -31,7 +31,7 @@ Successful calls will return status code 200 or 201. Other status codes that can
 
 The api supports the following actions:
 
-#### GET /api
+#### {% linkable_title GET /api %}
 Returns message if API is up and running.
 
 ```json
@@ -40,7 +40,7 @@ Returns message if API is up and running.
 }
 ```
 
-#### GET /api/events
+#### {% linkable_title GET /api/events %}
 Returns an array of event objects. Each event object contain event name and listener count.
 
 ```json
@@ -56,7 +56,7 @@ Returns an array of event objects. Each event object contain event name and list
 ]
 ```
 
-#### GET /api/services
+#### {% linkable_title GET /api/services %}
 Returns an array of service objects. Each object contains the domain and which services it contains.
 
 ```json
@@ -77,7 +77,7 @@ Returns an array of service objects. Each object contains the domain and which s
 ]
 ```
 
-#### GET /api/states
+#### {% linkable_title GET /api/states %}
 Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
 
 ```json
@@ -100,7 +100,7 @@ Returns an array of state objects. Each state has the following attributes: enti
 ]
 ```
 
-#### GET /api/states/<entity_id>
+#### {% linkable_title GET /api/states/<entity_id> %}
 Returns a state object for specified entity_id. Returns 404 if not found.
 
 ```json
@@ -115,7 +115,7 @@ Returns a state object for specified entity_id. Returns 404 if not found.
 }
 ```
 
-#### POST /api/states/<entity_id>
+#### {% linkable_title POST /api/states/<entity_id> %}
 Updates or creates the current state of an entity.
 
 Expects a JSON object that has atleast a state attribute:
@@ -142,7 +142,7 @@ Return code is 200 if the entity existed, 201 if the state of a new entity was s
 }
 ```
 
-#### POST /api/events/<event_type>
+#### {% linkable_title POST /api/events/<event_type> %}
 Fires an event with event_type
 
 You can pass an optional JSON object to be used as `event_data`.
@@ -161,7 +161,7 @@ Returns a message if successful.
 }
 ```
 
-#### POST /api/services/<domain>/<service>
+#### {% linkable_title POST /api/services/<domain>/<service> %}
 Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.
 
 You can pass an optional JSON object to be used as `service_data`.
@@ -198,7 +198,7 @@ Returns a list of states that have changed while the service was being executed.
 The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system. 
 </p>
 
-#### POST /api/event_forwarding
+#### {% linkable_title POST /api/event_forwarding %}
 Setup event forwarding to another Home Assistant instance.
 
 Requires a JSON object that represents the API to forward to.
@@ -219,7 +219,7 @@ It will return a message if event forwarding was setup successful.
 }
 ```
 
-#### DELETE /api/event_forwarding
+#### {% linkable_title DELETE /api/event_forwarding %}
 Cancel event forwarding to another Home Assistant instance.<br>
 
 Requires a JSON object that represents the API to cancel forwarding to.

source/developers/architecture.markdown

@@ -42,14 +42,14 @@ Home Assistant can be extended by **components**. Each component is responsible
 We can differentiate between two different types of
 components within Home Assistant.
 
-#### Components that interact with an Internet of Things domain
+#### {% linkable_title Components that interact with an Internet of Things domain %}
 These components will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices.
 
 For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches.
 
 If you are planning to add support for a new platform, please check out the [add new platform section]({{root_url}}/developers/add_new_platform.html).
 
-#### Components that respond to events that happen within Home Assistant
+#### {% linkable_title Components that respond to events that happen within Home Assistant %}
 These components provide small pieces of home automation logic or services that do common tasks within your house.
 
 For example the `device_sun_light_trigger` component tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines:
@@ -72,7 +72,7 @@ For example the `device_sun_light_trigger` component tracks the state of devices
 
 Another example of a home automation component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py).
 
-### The full picture
+### {% linkable_title The full picture %}
 
 When we put all the different pieces of Home Assistant together we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefor ommitted from the following picture.
 
@@ -85,7 +85,7 @@ When we put all the different pieces of Home Assistant together we see that we m
 
 Component's platform logic uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community.
 
-## Multiple connected instances
+## {% linkable_title Multiple connected instances %}
 
 Home Assistant supports running multiple synchronzied instances using a master-slave model. Whenever `events.fire` or `states.set` is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves.
 

source/developers/creating_components.markdown

@@ -25,7 +25,7 @@ target=TARGET_ENTITY
 
 `TARGET_ENTITY` should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be `light.Ceiling` or `switch.AC` (if you have these devices with those names).
 
-## Loading components
+## {% linkable_title Loading components %}
 
 A component will be loaded on start if a section (ie. `[light]`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths:
 
@@ -42,7 +42,7 @@ You can override a built-in component by having a component with the same name i
 Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
 </p>
 
-## Initializing components
+## {% linkable_title Initializing components %}
 
 After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in:
 
@@ -51,7 +51,7 @@ After loading, the bootstrapper will call `setup(hass, config)` method on the co
 | <code>hass</code> | The Home Assistant object. Call its methods to track time, register services, listen for events or track states: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L38) |
 | <code>config</code> | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration. |
 
-### Guidance on using the Home Assistant object
+### {% linkable_title Guidance on using the Home Assistant object %}
 The Home Assistant object contains three objects to help you interact with the system.
 
 | Object | Description |
@@ -60,7 +60,7 @@ The Home Assistant object contains three objects to help you interact with the s
 | <code>hass.events</code> | This is the EventBus. It allows you to trigger and listen for events.<br>[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L308). |
 | <code>hass.services</code> | This is the ServiceRegistry. It allows you to register services.<br>[See available methods](https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L589). |
 
-### Example on using the configuration parameter
+### {% linkable_title Example on using the configuration parameter %}
 If your configuration file containes the following lines:
 
 ```

source/developers/frontend.markdown

@@ -11,7 +11,7 @@ footer: true
 
 Home Assistant uses [Polymer](https://www.polymer-project.org/) for the frontend. Polymer allows building encapsulated and interoperable custom elements that extend HTML itself.
 
-# Turning on development mode
+# {% linkable_title Turning on development mode %}
 Home Assistant will by default serve the compiled version of the frontend. To change it so that the components are served separately, update your `home-assistant.conf` to have these lines:
 
 ```
@@ -26,7 +26,7 @@ After turning on development mode, you will have to install the webcomponents th
 Do not use development mode in production. Home Assistant uses aggresive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes.
 </p>
 
-# Building the frontend
+# {% linkable_title Building the frontend %}
 
 To build the frontend you need to install node and the npm packages bower and vulcanize.
 
@@ -36,7 +36,7 @@ npm install -g bower vulcanize
 
 After that you can run [`./build_frontend`](https://github.com/balloob/home-assistant/blob/master/build_frontend) from the project directory. This will take all the used webcomponents and 'vulcanize' it into a single file to be served by Home Assistant. The script also updates [`homeassistant/components/http/frontend.py`](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/frontend.py) with an MD5 hash of the frontend.
 
-# Adding state cards
+# {% linkable_title Adding state cards %}
 
 The main interface of Home Assistant is a list of current states in the State Machine. It will filter out the group states and offers options to filter by groups on the top.
 
@@ -51,7 +51,7 @@ To add your own card type, follow the following steps:
  2. Create a new component following the naming convention state-card-CARDTYPE.html in [/cards/](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/www_static/polymer/cards/).
  3. Import your new component in [/cards/state-card-content.html](https://github.com/balloob/home-assistant/blob/master/homeassistant/components/http/www_static/polymer/cards/state-card-content.html).
 
-# More info screens for custom types
+# {% linkable_title More info screens for custom types %}
 
 When you click on a card, the more info dialog will open for that card. This will allow you to see more information and more options to control that entity.
 

source/getting-started/index.markdown

@@ -40,7 +40,7 @@ If you're using Docker, you can use
 docker run -d --name="home-assistant" -v /path/to/homeassistant/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant
 ```
 
-## Configuring Home Assistant
+## {% linkable_title Configuring Home Assistant %}
 
 The configuration for Home Assistant lives by default in the `config` folder. The file `home-assistant.conf` is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at [`config/home-assistant.conf.example`](https://github.com/balloob/home-assistant/blob/master/config/home-assistant.conf.example).
 
@@ -65,7 +65,7 @@ api_password=YOUR_PASSWORD
 You can append <code>?api_password=YOUR_PASSWORD</code> to any url to log in automatically.
 </p>
 
-### Adding devices and services
+### {% linkable_title Adding devices and services %}
 
 Home Assistant will be able to automatically discover and configure any Google Chromecasts, Belkin WeMo switches and Philips Hue bridges in your network if you have [the discovery component]({{site_root}}/components/discovery.html) enabled (which is by default).
 
@@ -78,7 +78,7 @@ Not all devices can be discovered, so if you hae any of the following devices or
  * [Sun]({{site_root}}/components/sun.html)
  * [Add support for your own device or service]({{site_root}}/developers/add_new_platform.html)
 
-### Setting up Home Automation
+### {% linkable_title Setting up Home Automation %}
 
 When all your devices are set up it's time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics: