Add Jekyll terminology tooltip plugin (#26542)

Co-authored-by: Joakim Sørensen <joasoe@gmail.com>
This commit is contained in:
Franck Nijhof 2023-03-11 12:58:07 +01:00 committed by GitHub
parent 6cdee730e1
commit 8b71353f75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 404 additions and 83 deletions

View File

@ -0,0 +1,52 @@
module Jekyll
module HomeAssistant
class TerminologyTooltip < Liquid::Tag
def initialize(tag_name, args, tokens)
super
if args.strip =~ SYNTAX
@term = Regexp.last_match(1)
@text = Regexp.last_match(2)
else
raise SyntaxError, <<~MSG
Syntax error in tag 'term' while parsing the following options:
#{args}
Valid syntax:
{% term <term> [<text>] %}
MSG
end
end
def render(context)
entries = context.registers[:site].data["glossary"].select do |entry|
entry.key?("term") and (@term.casecmp(entry["term"]).zero? or (entry.key?("aliases") and entry["aliases"].any?{ |s| s.casecmp(@term)==0 }))
end
raise ArgumentError, "Term #{@term} was not found in the glossary" if entries.length == 0
raise ArgumentError, "Term #{@term} is in the glossary multiple times" if entries.length > 1
raise ArgumentError, "Term #{@term} is missing a definition" unless entries[0].key?("definition")
glossary = entries[0]
definition = glossary["excerpt"] || glossary["definition"]
if glossary.key?("link")
rendered_link = Liquid::Template.parse(glossary["link"]).render(context).strip
link = "<br><a class='terminology-link' href='#{rendered_link}' target='_blank'>[Learn more]</a>"
end
tooltip = "<span class='terminology-tooltip'>#{definition}#{link || ""}</span>"
"<span class='terminology'>#{@text || @term}#{tooltip}</span>"
end
private
SYNTAX = %r!^(\w+?|".+?")(?:\s+(\w+|".+"))?$!.freeze
end
end
end
Liquid::Template.register_tag('term', Jekyll::HomeAssistant::TerminologyTooltip)

View File

@ -0,0 +1,46 @@
.terminology {
position: relative;
border-bottom: 2px dotted $primary-color;
cursor: help;
&:hover .terminology-tooltip {
visibility: visible;
opacity: 1;
}
.terminology-tooltip {
visibility: hidden;
width: 250px;
background-color: $primary-color;
color: #fff;
font-size: 0.8em;
padding: 8px;
border-radius: 8px;
opacity: 0;
transition: opacity 0.5s;
position: absolute;
z-index: 1;
bottom: 100%;
left: 50%;
margin-left: -125px;
a {
color: #fff;
font-weight: 500;
}
&:after {
content: " ";
position: absolute;
top: 100%;
left: 50%;
margin-left: -5px;
border-width: 5px;
border-style: solid;
border-color: $primary-color transparent transparent transparent;
}
}
}

View File

@ -9,3 +9,4 @@
@import 'custom/layout';
@import 'custom/getting_started';
@import 'custom/tabbed_block';
@import 'custom/terminology_tooltip';

View File

@ -1,78 +1,299 @@
- topic: Action
description: "An [Action](/docs/automation/action/) is an event that can be fired as a response to a trigger, once all conditions have been met."
- topic: Add-on
description: "Add-ons are additional standalone third-party software packages that can be installed on Home Assistant OS. Most of these, add-on provided, applications can be integrated into Home Assistant using integrations. Examples of add-ons are: an MQTT broker, database service or a file server."
- topic: Automation
description: "[Automations](/docs/automation/) connect one or more triggers to one or more actions in a 'when trigger then do action' fashion with additional optional conditions. For example, an automation might connect the trigger 'sunset' to the action 'turn the lights on' but only if the condition 'someone is home' is met. Pre-made automations for common use-cases are available via [the blueprints feature](/docs/automation/using_blueprints/)."
- topic: Binary sensor
description: "A [binary sensor](/integrations/binary_sensor) returns information about things that only have two states - such as on or off."
- topic: Component
description: "Integrations (see below) used to be known as components."
- topic: Condition
description: "[Conditions](/docs/scripts/conditions/) are an optional part of an automation that will prevent an action from firing if they are not met."
- topic: Cover
description: "[Covers](/integrations/cover) are devices such as blinds, garage doors, etc that can be opened and closed and optionally set to a specific position."
- topic: Customize
description: "[Customization](/docs/configuration/customizing-devices/) allows you to overwrite the default parameters of your devices in the configuration."
- topic: Device
description: "A device is a named collection of entities that all represent the same physical/logical unit, which can do or observe something. An example for a device would be a smart plug named 'Coffee Machine' which provides a `switch` entity plus one or more `sensor` entities for power monitoring or similar."
- topic: Device tracker
description: "[Device trackers](/integrations/device_tracker) are used to track the presence, or location, of a device."
- topic: Discovery
description: "Discovery is the automatic setup of zeroconf/mDNS and uPnP devices after they are discovered."
- topic: Domain
description: "Each integration in Home Assistant has a unique identifier: a domain. All of the entities and services available in Home Assistant are provided by integrations and thus belong to such a domain. The first part of the entity or service, before the `.` shows the domain they belong to. For example `light.kitchen` is an entity in the `light` domain from the [light integration](/integrations/light), while `hue.activate_scene` is the `activate_scene` service for the `hue` domain which belongs to the [Hue integration](/integrations/hue)."
- topic: Entity
description: "An entity is the representation of a single control or data point of a device or service inside Home Assistant. A single device or service can thus provide multiple entities to be able to monitor and control all features a device provides. For example, a combined temperature and humidity sensor, in general, provides two `sensor` entities. One for the temperature (e.g., `sensor.temperature` with state `21.0` and unit `°C`) and one for the humity (e.g., `sensor.humidity` with state `65.4` and unit `%`)."
- topic: Event
description: "An [event](/docs/configuration/events/) is when something happens."
- topic: Frontend
description: "The [frontend](/integrations/frontend/) is a necessary component for the UI, it is also where you can define your themes."
- topic: Group
description: "[Groups](/integrations/group/) are a way to organize your entities into a single unit."
- topic: HASS
description: "HASS or [hass](/docs/tools/hass/) is often used as an abbreviation for Home Assistant. It is also the command-line tool."
- topic: HassOS
description: "Another name for Home Assistant Operating System"
- topic: Home Assistant Core
description: Home Assistant Core is a Python program. It can be run on various operating systems and is the basis for Home Assistant. When people are talking about Home Assistant Core they usually refer to a standalone installation method that can be installed using a Virtual Environment or Docker. Home Assistant Core does not use the Home Assistant Supervisor.
- topic: Home Assistant Supervised (Previously Hass.io)
description: "Home Assistant Supervised is a full UI managed home automation ecosystem that runs Home Assistant, the Home Assistant Supervisor and add-ons. It comes pre-installed on Home Assistant OS, but can be installed on any Linux system. It leverages Docker, which is managed by the Home Assistant Supervisor."
- topic: Home Assistant Supervisor
description: "The Home Assistant Supervisor is a program that manages a Home Assistant installation, taking care of installing and updating Home Assistant, add-ons, itself and, if used, updating the Home Assistant Operating System."
- topic: Home Assistant Operating System
description: "Home Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. The Home Assistant Supervisor can keep it up to date, removing the need for you to manage an operating system."
- topic: Integration
description: "[Integrations](/integrations/) connect and integrates Home Assistant with devices, services, and more. Such an integration contains all the logic that takes care of vendor- and device-specific implementations such as authentication or special protocols and brings those into Home Assistant in a standardized way. For example, the [Hue](/integrations/hue) integration integrates the Philips Hue bridge and its connected bulbs into Home Assistant, making them available as Home Assistant light entities you can control."
- topic: Lovelace
description: "Lovelace is the original code name of the UI that is now known as [Home Assistant dashboards](/dashboards)."
- topic: Light
description: "A [light](/integrations/light) has a brightness you can control, and optionally color temperature or RGB color control."
- topic: Notification
description: "You can use [notifications](/integrations/#notifications) to send messages, pictures, and more, to devices."
- topic: Packages
description: "[Packages](/docs/configuration/packages/) allow you to bundle different component configurations together."
- topic: Platform
description: "[Platforms](/docs/configuration/platform_options/) are building blocks provided by some integrations to be used by other integrations. For example, the [Light](/integrations/light) integration provides the `light platform` that is utilized by all integrations providing `light` entities such as e.g. [Hue](/integrations/hue)."
- topic: Scene
description: "[Scenes](/integrations/scene/) capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red."
- topic: Script
description: "[Scripts](/docs/scripts/) are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on."
- topic: Sensor
description: "[Sensors](/integrations/sensor) return information about a thing, for instance the level of water in a tank."
- topic: Selectors
description: "[Selectors](/docs/blueprint/selectors/) are components for the user interface. Some selectors can, for example, show a toggle button to turn something on or off, while another select can filter a list of devices to show only devices that have motion-sensing capabilities."
- topic: Service
description: "[Services](/docs/scripts/service-calls/) are called to perform actions."
- topic: Switch
description: "[Switches](/integrations/switch) are things that have two states you can select between, such as turning on or off a socket."
- topic: Template
description: "A [template](/docs/automation/templating/) is an automation definition that can include variables for the service or data from the trigger values. This allows automations to generate dynamic actions."
- topic: Trigger
description: "A [trigger](/docs/automation/trigger/) is a set of values or conditions of a platform that are defined to cause an automation to run."
- topic: TTS
description: "TTS ([text to speech](/integrations/tts)) allows Home Assistant to talk to you."
- topic: Variables
description: "[Variables](/docs/scripts/#variables) are used to store values in memory that can be processed e.g. in a script."
- topic: Zone
description: "[Zones](/integrations/zone/) are areas that can be used for presence detection."
## Glossary
#
# Format is a list of terms, each term is a dictionary with the following keys:
# - term: The term to define (required)
# - definition: The definition of the term (required)
# - excerpt: Short excerpt of the definition, overrides definition for tooltips (optional)
# - link: A URL to link to for more information (optional)
# - aliases: A list of aliases for the term (optional)
#
- term: Action
definition: >
An action is an command that can be fired. For example, turning on a light.
Actions used in many places, most notably in automations and scripts.
aliases:
- actions
link: /docs/automation/action/
- term: Add-on
definition: >
Add-ons are additional standalone third-party software packages that can be
installed on Home Assistant OS. Most of these, add-on provided, applications
can be integrated into Home Assistant using integrations. Examples of
add-ons are: an MQTT broker, database service or a file server.
excerpt: >
Add-ons are additional standalone third-party software packages that can be
installed on Home Assistant OS.
- term: Automation
definition: >
Automations connect one or more triggers to one or more actions in a
'when trigger then do action' fashion with additional optional conditions.
For example, an automation might connect the trigger 'sunset' to the action
'turn the lights on' but only if the condition 'someone is home' is met.
Pre-made automations for common use-cases are available via
[the blueprints feature](/docs/automation/using_blueprints/).
excerpt: >
Automations in Home Assistant allow you to automatically respond to things
that happen in and around your home.
link: /docs/automation/
aliases:
- automations
- term: Binary sensor
definition: >
A binary sensor returns information about things that only have two states -
such as on or off.
link: /integrations/binary_sensor
- term: Component
definition: >
Better known as: Integrations. Integrations used to be known as components.
- term: Condition
definition: >
Conditions are an optional part of an automation that will prevent an
action from firing if they are not met.
link: /docs/scripts/conditions/
- term: Cover
definition: >
Covers are devices such as blinds, garage doors, etc that can be opened
and closed and optionally set to a specific position.
link: /integrations/cover
- term: Customize
definition: >
Customization allows you to overwrite the default parameters of your
devices in the configuration.
- term: Device
definition: >
A device is a named collection of entities that all represent the same
physical/logical unit, which can do or observe something. An example,
for a device would be a smart plug named 'Coffee Machine' which provides
a `switch` entity plus one or more `sensor` entities for power monitoring
or similar.
excerpt: >
A device is a named collection of entities that all represent the same
physical/logical unit, which can do or observe something.
- term: Device tracker
definition: >
Device trackers are used to track the presence, or location, of a device.
link: /integrations/device_tracker
- term: Discovery
definition: >
Discovery is the automatic setup of zeroconf/mDNS and uPnP devices after
they are discovered.
- term: Domain
definition: >
Each integration in Home Assistant has a unique identifier:
a domain. All of the entities and services available in Home Assistant
are provided by integrations and thus belong to such a domain. The first
part of the entity or service, before the `.` shows the domain they belong
to. For example `light.kitchen` is an entity in the `light` domain from
the [light integration](/integrations/light), while `hue.activate_scene`
is the `activate_scene` service for the `hue` domain which belongs to
the [Hue integration](/integrations/hue).
excerpt: >
Each integration in Home Assistant has a unique identifier: The domain.
It is often shown as the first part (before the dot) of entity IDs.
- term: Entity
definition: >
An entity is the representation of a single control or data point of a
device or service inside Home Assistant. A single device or service can
thus provide multiple entities to be able to monitor and control all
features a device provides. For example, a combined temperature and
humidity sensor, in general, provides two `sensor` entities. One for the
temperature (e.g., `sensor.temperature` with state `21.0` and unit `°C`)
and one for the humity
(e.g., `sensor.humidity` with state `65.4` and unit `%`).
excerpt: >
An entity is the representation of a single control or data point of a
device or service inside Home Assistant.
- term: Event
definition: >
An event is when something happens.
link: /docs/configuration/events/
- term: Frontend
definition: >
The frontend is a necessary component for the UI, it is also where you
can define your themes.
link: /integrations/frontend/
- term: Group
definition: >
Groups are a way to organize your entities into a single unit.
link: /integrations/group/
- term: HASS
definition: >
HASS or [hass](/docs/tools/hass/) is often used as an abbreviation for
Home Assistant. It is also the command-line tool.
- term: HassOS
definition: >
Another name for Home Assistant Operating System
link: /hassio/installation/
- term: Home Assistant Core
definition: >
Home Assistant Core is a Python program. It can be run on various operating
systems and is the basis for Home Assistant. When people are talking about
Home Assistant Core they usually refer to a standalone installation method
that can be installed using a Virtual Environment or Docker. Home Assistant
Core does not use the Home Assistant Supervisor.
excerpt: >
Home Assistant Core is the hart of Home Assistant itself. It is a Python
program that powers every installation type, but can be installed standalone.
- term: Home Assistant Supervised
definition: >
Home Assistant Supervised is a full UI managed home automation ecosystem that
runs Home Assistant, the Home Assistant Supervisor and add-ons. It comes
pre-installed on Home Assistant OS, but can be installed on any Linux system.
It leverages Docker, which is managed by the Home Assistant Supervisor.
excerpt: >
Home Assistant Supervised is the full Home Assistant ecosystem, without the
Home Assistant Operating System.
- term: Home Assistant Supervisor
definition: >
The Home Assistant Supervisor is a program that manages a Home Assistant
installation, taking care of installing and updating Home Assistant,
add-ons, itself and, if used, updating the Home Assistant Operating System.
- term: Home Assistant Operating System
definition: >
Home Assistant OS, the Home Assistant Operating System, is an embedded,
minimalistic, operating system designed to run the Home Assistant ecosystem
on single board computers (like the Raspberry Pi) or Virtual Machines.
The Home Assistant Supervisor can keep it up to date, removing the need for
you to manage an operating system.
excerpt: >
Home Assistant OS, the Home Assistant Operating System, is an embedded,
minimalistic, operating system designed to run the Home Assistant ecosystem.
- term: Integration
definition: >
Integrations connect and integrates Home Assistant with devices, services,
and more. Such an integration contains all the logic that takes care of
vendor- and device-specific implementations such as authentication or
special protocols and brings those into Home Assistant in a standardized
way. For example, the [Hue](/integrations/hue) integration integrates
the Philips Hue bridge and its connected bulbs into Home Assistant, making
them available as Home Assistant light entities you can control.
excerpt: >
Integrations connect and integrates Home Assistant with your devices,
services, and more.
link: /integrations/
- term: Lovelace
definition: >
Lovelace is the original code name of the UI that is now known as
[Home Assistant dashboards](/dashboards).
- term: Light
definition: >
A light has a brightness you can control, and optionally color temperature
or RGB color control.
link: /integrations/light
- term: Notification
definition: >
You can use notifications to send messages, pictures, and more, to devices.
link: /integrations/#notifications
- term: Packages
definition: >
Packages allow you to bundle different component configurations together.
link: /docs/configuration/packages/
- term: Platform
definition: >
Platforms are building blocks provided by some integrations to be used by
other integrations. For example, the [Light](/integrations/light)
integration provides the `light platform` that is utilized by all
integrations providing `light` entities such
as e.g. [Hue](/integrations/hue).
excerpt: >
Platforms are building blocks provided by some integrations to be used by
other integrations.
link: /docs/configuration/platform_options/
- term: Scene
definition: >
Scenes capture the states you want certain entities to be. For example,
a scene can specify that light A should be turned on and light B should
be bright red.
link: /integrations/scene/
- term: Script
definition: >
Scripts are components that allow users to specify a sequence of actions
to be executed by Home Assistant when turned on.
link: /docs/scripts/
- term: Sensor
definition: >
Sensors return information about a thing, for instance the level of water
in a tank.
link: /integrations/sensor/
- term: Selectors
definition: >
Selectors are components for the user interface. Some selectors can,
for example, show a toggle button to turn something on or off, while another
select can filter a list of devices to show only devices that have
motion-sensing capabilities.
excerpt: >
Selectors are components for the user interface. Like toggle, dropdown,
and more.
link: /docs/blueprint/selectors/
- term: Service
definition: >
Services are called to perform actions.
link: /docs/scripts/service-calls/
- term: Switch
definition: >
Switches are things that have two states you can select between, such as
turning on or off a socket.
link: /integrations/switch/
- term: Template
definition: >
A template is an automation definition that can include variables for the
service or data from the trigger values. This allows automations to generate
dynamic actions.
link: /docs/automation/templating/
- term: Trigger
definition: >
A trigger is a set of values or conditions of a platform that are defined
to cause an automation to run.
link: /docs/automation/trigger/
- term: TTS
definition: >
TTS (text to speech) allows Home Assistant to talk to you.
link: /integrations/tts/
- term: Variables
definition: >
Variables are used to store values in memory that can be processed
e.g. in a script.
link: /docs/scripts/#variables
- term: Zone
definition: >
Zones are areas that can be used for presence detection.
link: /integrations/zone/

View File

@ -3,15 +3,16 @@ title: "Glossary"
description: "Home Assistant's Glossary."
---
{% assign entries = site.data.glossary | sort: 'topic' %}
{% assign entries = site.data.glossary | sort: 'term' %}
The glossary covers terms which are used around Home Assistant.
{% configuration_basic %}
{% for entry in entries %}
"{{ entry.topic }}":
description: "{{ entry.description }}"
"{{ entry.term }}":
description: "{{ entry.definition }}
{% if entry.link %}<br />[Read more about: {{ entry.term }}]({{ entry.link }}){% endif %}"
{% endfor %}
{% endconfiguration_basic %}

View File

@ -5,7 +5,7 @@ toc: true
no_toc: true
---
Scripts are a sequence of actions that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in [automations] and [Alexa/Amazon Echo] configurations.
Scripts are a sequence of {% term actions %} that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in {% term automations %} and [Alexa/Amazon Echo] configurations.
When the script is executed within an automation the `trigger` variable is available. See [Available-Trigger-Data](/docs/automation/templating/#available-trigger-data).