diff --git a/docs/assets/sections.png b/docs/assets/sections.png new file mode 100644 index 000000000..d1d68d5a5 Binary files /dev/null and b/docs/assets/sections.png differ diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 56ed77c85..f9281da26 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,36 +1,44 @@ [data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after { - position: absolute; - top: .3rem; - right: .3rem; - display: block; - padding: .1rem .4rem; - color: var(--md-default-fg-color--lighter); - font-weight: bold; - font-size: .8rem; - border: .05rem solid var(--md-default-fg-color--lighter); - border-radius: .1rem; - content: "/"; - } + position: absolute; + top: 0.3rem; + right: 0.3rem; + display: block; + padding: 0.1rem 0.4rem; + color: var(--md-default-fg-color--lighter); + font-weight: bold; + font-size: 0.8rem; + border: 0.05rem solid var(--md-default-fg-color--lighter); + border-radius: 0.1rem; + content: "/"; +} [data-md-color-scheme="default"][data-md-color-primary="black"] { - [data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after { - color: var(--md-default-bg-color--lighter); - border-color: var(--md-default-bg-color--lighter); - } + [data-md-toggle="search"]:not(:checked) ~ .md-header .md-search__form::after { + color: var(--md-default-bg-color--lighter); + border-color: var(--md-default-bg-color--lighter); + } } #glimeRoot * { - font-family: var(--md-text-font) !important; + font-family: var(--md-text-font) !important; } #carbonads { - margin-top: 10px; + margin-top: 10px; } #carbon-responsive { - --carbon-padding: 1em; - --carbon-max-char: 20ch; - --carbon-bg-primary: var(--md-default-bg-color) !important; - --carbon-bg-secondary: var(--md-default-fg-color--lightest) !important; - --carbon-text-color: var(--md-typeset-color) !important; + --carbon-padding: 1em; + --carbon-max-char: 20ch; + --carbon-bg-primary: var(--md-default-bg-color) !important; + --carbon-bg-secondary: var(--md-default-fg-color--lightest) !important; + --carbon-text-color: var(--md-typeset-color) !important; +} + +.md-typeset__table { + width: 100%; +} + +.md-typeset table:not([class]) { + display: table; } diff --git a/docs/widgets/authoring/component.md b/docs/widgets/authoring/component.md index 1a14d4196..42c65787b 100644 --- a/docs/widgets/authoring/component.md +++ b/docs/widgets/authoring/component.md @@ -61,5 +61,42 @@ This hook is used to fetch data from the API. We cover this hook in more detail #### Components -- ``: This component is a wrapper for the widget. It provides a consistent layout for all widgets. -- ``: This component is used to display a key-value pair. It takes a label and value as props. +Homepage provides a set of components to help you build your widget UI. These components are designed to provide a consistent layout, and all widgets are expected to use these components. + +![Component Sections](/assets/sections.png) + +**``** + +This component is a wrapper for the widget. It provides a consistent layout for all widgets. + +```js + +``` + +`service` is a prop that is passed to the widget component. It contains information about the service that the widget is displaying. + +If there is an error fetching data from the API, the `error` prop can be passed to the `Container` component. + +```js + +``` + +**``** + +This component is used to display a key-value pair. It takes a label and value as props. + +```js + +``` + +The `label` prop is used to look up the translation key in the translation files. The `value` prop is used to display the value of the block. To learn more about translations, please refer to the [Translations Guide](translations.md). + +If there is no data available, the `Block` component can be used to display a placeholder layout. + +```js + + + + + +``` diff --git a/docs/widgets/authoring/translations.md b/docs/widgets/authoring/translations.md index 8a47f7c78..06a6e39da 100644 --- a/docs/widgets/authoring/translations.md +++ b/docs/widgets/authoring/translations.md @@ -2,3 +2,79 @@ title: Translations Guide description: Tips and tricks for translating and localizing Homepage widgets. --- + +All text and numerical content in widgets should be translated and localized. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage). + +The Homepage community prides itself on being multilingual, and we strongly encourage you to add translations for your widgets. + +## Translations + +Homepage uses the [next-i18next](https://github.com/i18next/next-i18next) library to handle translations. This library provides a set of hooks and utilities to help you localize your widgets, and Homepage has extended this library to support additional features. + +=== "component.jsx" + + ```js + import { useTranslation } from "next-i18next"; + + import Container from "components/services/widget/container"; + import Block from "components/services/widget/block"; + + export default function Component() { + const { t } = useTranslation(); + + return ( + + + + + + ); + } + ``` + +=== "en.json" + + ```json + "yourwidget": { + "key1": "Value 1", + "key2": "Value 2", + "key3": "Value 3" + } + ``` + +## Common Translations + +Homepage provides a set of common translations that you can use in your widgets. These translations are used to format numerical content, dates, and other common elements. + +### Numbers + +| Key | Translation | Description | +| --------------------- | --------------- | -------------------------------- | +| `common.bytes` | `1,000 B` | Format a number in bytes. | +| `common.bits` | `1,000 bit` | Format a number in bits. | +| `common.bbytes` | `1 KiB` | Format a number in binary bytes. | +| `common.bbits` | `1 Kibit` | Format a number in binary bits. | +| `common.byterate` | `1,000 B/s` | Format a byte rate. | +| `common.bibyterate` | `1 KiB/s` | Format a binary byte rate. | +| `common.bitrate` | `1,000 bit/s` | Format a bit rate. | +| `common.bibitrate` | `1 Kibit/s` | Format a binary bit rate. | +| `common.percent` | `50%` | Format a percentage. | +| `common.number` | `1,000` | Format a number. | +| `common.ms` | `1,000 ms` | Format a number in milliseconds. | +| `common.date` | `2024-01-01` | Format a date. | +| `common.relativeDate` | `1 day ago` | Format a relative date. | +| `common.uptime` | `1 day, 1 hour` | Format an uptime. | + +### Text + +| Key | Translation | Description | +| ------------------ | ----------- | ------------------ | +| `resources.cpu` | `CPU` | CPU usage. | +| `resources.mem` | `MEM` | Memory usage. | +| `resources.total` | `Total` | Total resource. | +| `resources.free` | `Free` | Free resource. | +| `resources.used` | `Used` | Used resource. | +| `resources.load` | `Load` | Load value. | +| `resources.temp` | `TEMP` | Temperature value. | +| `resources.max` | `Max` | Maximum value. | +| `resources.uptime` | `UP` | Uptime. |