diff --git a/.prettierignore b/.prettierignore index 8eb6547..9e2c9a5 100644 --- a/.prettierignore +++ b/.prettierignore @@ -8,6 +8,9 @@ # directories .changeset +.github # files -pnpm-lock.yaml \ No newline at end of file +pnpm-lock.yaml +*.md +*.mdx \ No newline at end of file diff --git a/docs/src/content/docs/guides/dashboard-customization.mdx b/docs/src/content/docs/guides/dashboard-customization.mdx index 0215f43..b12595b 100644 --- a/docs/src/content/docs/guides/dashboard-customization.mdx +++ b/docs/src/content/docs/guides/dashboard-customization.mdx @@ -25,27 +25,26 @@ By default, Lunaria will add a default title and description for your dashboard. 2. Add the [`dashboard.description`](/reference/configuration/#dashboarddescription) option to your Lunaria config: ```json title="lunaria.config.json" add={4} - { - "dashboard": { - "title": "Lunaria Localization Status", - "description": "Localization status dashboard for the Lunaria project." - } - } + { + "dashboard": { + "title": "Lunaria Localization Status", + "description": "Localization status dashboard for the Lunaria project." + } + } ``` - - + ## Canonical URL If you desire to publicize different versions of your dashboard (e.g. localized versions of the dashboard itself), it might be helpful to set a [canonical URL](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls#rel-canonical-link-method) to optimize your dashboard's ranking on search engines. -To add a canonical URL, you can set [`dashboard.site`](/reference/configuration/#dashboardsite) in your Lunaria configuration file: +To add a canonical URL, you can set [`dashboard.site`](/reference/configuration/#dashboardsite) in your Lunaria configuration file: ```json title="lunaria.config.json" add={3} { - "dashboard": { - "site": "https://localization.lunaria.dev/" - } + "dashboard": { + "site": "https://localization.lunaria.dev/" + } } ``` @@ -65,20 +64,20 @@ External favicons are favicons you load through another URL as a resource. You c ```json title="lunaria.config.json" add={4-13} { - "dashboard": { - "favicon": { - "external": [ - { - "link": "https://lunaria.dev/favicon.svg", - "type": "image/svg+xml" - }, - { - "link": "https://lunaria.dev/favicon.ico", - "type": "image/x-icon" - } - ] - } - } + "dashboard": { + "favicon": { + "external": [ + { + "link": "https://lunaria.dev/favicon.svg", + "type": "image/svg+xml" + }, + { + "link": "https://lunaria.dev/favicon.ico", + "type": "image/x-icon" + }, + ] + } + } } ``` @@ -89,40 +88,43 @@ An inline favicon is a local [`.svg` favicon appended to your dashboard through 1. Add your favicon SVG file to a directory in your project (e.g. `src/assets/`): -{' '} - -- src/ - assets/ - **favicon.svg** - lunaria.config.json + + - src/ + - assets/ + - **favicon.svg** + - lunaria.config.json + -2. Add the path to your favicon as the `inline` property of [`dashboard.favicon`](/reference/configuration/#dashboardfavicon) in your Lunaria config: +2. Add the path to your favicon as the `inline` property of [`dashboard.favicon`](/reference/configuration/#dashboardfavicon) in your Lunaria config: - ```json title="lunaria.config.json" add={4} - { - "dashboard": { - "favicon": { - "inline": "./src/assets/favicon.svg" - } - } + ```json title="lunaria.config.json" add={4} + { + "dashboard": { + "favicon": { + "inline": "./src/assets/favicon.svg" } - ``` - - + } + } + ``` + ## Hidden path bases -The dashboard contains several paths as links to your source and localized content. These can be quite lengthy depending on how far they are from your project's root directory. For example, if the unique part of your content files' paths starts only after `src/content/docs/`, you might want to hide this portion of the path and only show what's relevant, e.g. `guides/my-content.mdx`. +The dashboard contains several paths as links to your source and localized content. These can be quite lengthy depending on how far they are from your project's root directory. For example, if the unique part of your content files' paths starts only after `src/content/docs/`, you might want to hide this portion of the path and only show what's relevant, e.g. `guides/my-content.mdx`. To do so, you can set the [`dashboard.basesToHide`](/reference/configuration/#dashboardbasestohide) option in your Lunaria config with all the desired path bases to hide. This example assumes you're tracking content files that start at `src/content/docs/` or `src/i18n/`: ```json title="lunaria.config.json" add={3} { - "dashboard": { - "basesToHide": ["src/content/docs/", "src/i18n/"] - } + "dashboard": { + "basesToHide": ["src/content/docs/", "src/i18n/"] + } } ``` With this, references to paths like `src/content/docs/guide.mdx` and `src/i18n/dictionary.ts` will be shortened to their unique parts, namely `guide.mdx` and `dictionary.ts`. + ## Custom CSS The dashboard can be further customized by adding your own custom CSS, allowing you to modify or extend the default styles provided by Lunaria out of the box. @@ -136,20 +138,19 @@ The dashboard can be further customized by adding your own custom CSS, allowing } ``` -2. Add the path to your CSS file to your Lunaria config's [`dashboard.customCss`](/reference/configuration/#dashboardcustomcss) array property: - - ```json title="lunaria.config.json" add={3} - { - "dashboard": { - "customCss": ["./src/styles/lunaria.css"] - } - } - ``` +2. Add the path to your CSS file to your Lunaria config's [`dashboard.customCss`](/reference/configuration/#dashboardcustomcss) array property: - + ```json title="lunaria.config.json" add={3} + { + "dashboard": { + "customCss": ["./src/styles/lunaria.css"] + } + } + ``` + :::tip -Check out the Lunaria repository to see [all the available CSS custom properties set by Lunaria and its implementation](https://github.com/yanthomasdev/lunaria/blob/main/packages/core/src/dashboard/styles.ts). +Check out the Lunaria repository to see [all the available CSS custom properties set by Lunaria and its implementation](https://github.com/yanthomasdev/lunaria/blob/main/packages/core/src/dashboard/styles.ts). ::: ## Custom labels and language @@ -162,11 +163,11 @@ For example, you can change the default message shown when a locale's localizati ```json title="lunaria.config.json" add={4} { - "dashboard": { - "ui": { - "statusByLocale.completeLocalization": "No missing or outdated changes found, congratulations!" - } - } + "dashboard": { + "ui": { + "statusByLocale.completeLocalization": "No missing or outdated changes found, congratulations!" + } + } } ``` @@ -182,17 +183,17 @@ Some labels, suffixed with `Format` in their name, come with named `{}` blocks t "statusByLocale.detailsTitleFormat": "{locale_name} ({locale_tag})", ``` -These can also be changed, though it is highly recommended to not remove any of the `{}` blocks present by default, as that would mean possibly not inserting a dynamic value that was expected. +These can also be changed, though it is highly recommended to not remove any of the `{}` blocks present by default, as that would mean possibly not inserting a dynamic value that was expected. For example, you could modify your dashboard to show the language details' summary from the format `Deutsch (de)` to `Deutsch - de` by making a small change in the default `statusByLocale.detailsTitleFormat` value: ```json title="lunaria.config.json" add={4} { - "dashboard": { - "ui": { - "statusByLocale.detailsTitleFormat": "{locale_name} - {locale_tag}" - } - } + "dashboard": { + "ui": { + "statusByLocale.detailsTitleFormat": "{locale_name} - {locale_tag}", + } + } } ``` @@ -204,19 +205,19 @@ For example, that's how you could go about changing your dashboard's language to ```json title="lunaria.config.json" add={4-6} { - "dashboard": { - "ui": { - "lang": "pt-BR", - "statusByFile.heading": "Estado da localização por arquivo", - "statusByFile.tableRowFile": "Arquivo" - } - } + "dashboard": { + "ui": { + "lang": "pt-BR", + "statusByFile.heading": "Estado da localização por arquivo", + "statusByFile.tableRowFile": "Arquivo", + } + } } ``` ## Custom UI elements -Lunaria's dashboard was designed to be flexible and easily customizable through [custom CSS](#custom-css) and the available [configuration options](/reference/configuration/#dashboard-options). When that's not enough, Lunaria allows you to extend and override your dashboard's UI using its [Renderer API](/reference/renderer/). +Lunaria's dashboard was designed to be flexible and easily customizable through [custom CSS](#custom-css) and the available [configuration options](/reference/configuration/#dashboard-options). When that's not enough, Lunaria allows you to extend and override your dashboard's UI using its [Renderer API](/reference/renderer/). 1. Add a new `renderer.config.ts` or `renderer.config.js` file to your project with the following content: @@ -229,19 +230,18 @@ Lunaria's dashboard was designed to be flexible and easily customizable through }); ``` -2. Add the path to your renderer file to your Lunaria config's [`renderer`](/reference/configuration/#renderer) configuration property: - - ```json title="lunaria.config.json" add={2} - { - "renderer": "./renderer.config.ts" - } - ``` +2. Add the path to your renderer file to your Lunaria config's [`renderer`](/reference/configuration/#renderer) configuration property: - + ```json title="lunaria.config.json" add={2} + { + "renderer": "./renderer.config.ts" + } + ``` + ### Custom components -All UI elements in Lunaria are built without the use of frameworks, using only the good ol' HTML. To improve the authoring experience, Lunaria comes with a built-in `html` tagged template to help you build your own components. +All UI elements in Lunaria are built without the use of frameworks, using only the good ol' HTML. To improve the authoring experience, Lunaria comes with a built-in `html` tagged template to help you build your own components. :::tip[Syntax highlighting] You can get syntax highlighting and language support inside `html` using the [`lit-html` VSCode extension](https://marketplace.visualstudio.com/items?itemName=bierner.lit-html) or the [`vim-jsx-pretty` plugin for Vim](https://github.com/MaxMEllon/vim-jsx-pretty). @@ -252,8 +252,7 @@ A component in Lunaria is a function that receives a few parameters and returns ```ts title="example-component.ts" import { html } from '@lunariajs/core'; -const CustomParagraph = () => - html`

This is my custom paragraph component!

`; +const CustomParagraph = () => html`

This is my custom paragraph component!

`; ``` Since these components are [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals), you can interpolate values using the `${}` notation as you normally would in JavaScript: @@ -267,10 +266,10 @@ const ColorComponent = () => html`

My favorite color is ${favoriteColor}!

` ```
- See the resulting HTML - ```html -

My favorite color is red!

- ``` +See the resulting HTML +```html +

My favorite color is red!

+```
You can also interpolate over lists of values (e.g. arrays) using the `.map()` method: @@ -278,25 +277,22 @@ You can also interpolate over lists of values (e.g. arrays) using the `.map()` m ```ts title="interpolating-list.ts" import { html } from '@lunariajs/core'; -const catColors = ['grey', 'white', 'black', 'orange', 'buff']; +const catColors = ["grey", "white", "black", "orange", "buff"]; -const CatColorsList = () => - html``; +const CatColorsList = () => html`` ```
- See the resulting HTML - ```html - - ``` +See the resulting HTML +```html + +```
:::caution @@ -318,21 +314,20 @@ Elements can be slotted into the dashboard with the [renderer's `slots` property export default defineRendererConfig({}); ``` -2. Add the created component to one of the available slots in the [`slots` property](/reference/renderer/#slots). Here, the `head` slot will be used to insert the component into the dashboard's [`` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head): - - ```ts title="renderer.config.ts" add={6-8} - import { defineRendererConfig, html } from '@lunariajs/core'; +2. Add the created component to one of the available slots in the [`slots` property](/reference/renderer/#slots). Here, the `head` slot will be used to insert the component into the dashboard's [`` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head): - const NoIndex = () => html``; + ```ts title="renderer.config.ts" add={6-8} + import { defineRendererConfig, html } from '@lunariajs/core'; - export default defineRendererConfig({ - slots: { - head: NoIndex, - } - }); - ``` + const NoIndex = () => html``; - + export default defineRendererConfig({ + slots: { + head: NoIndex, + } + }); + ``` + ### Overriding elements @@ -350,20 +345,16 @@ Elements can also be overridden in the dashboard with the [renderer's `overrides ``` 2. Add the created component to one of the available overrides in the [`overrides` property](/reference/renderer/#overrides). Here, the `body` slot will be used to insert the component and override everything inside the dashboard's [`` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body): + + ```ts title="renderer.config.ts" add={6-8} + import { defineRendererConfig, html } from '@lunariajs/core'; - ```ts title="renderer.config.ts" add={6-8} - import { defineRendererConfig, html } from '@lunariajs/core'; - - const NewBody = (config, status) => - html``; - - export default defineRendererConfig({ - overrides: { - body: NewBody, - }, - }); - ``` + const NewBody = (config, status) => html``; + export default defineRendererConfig({ + overrides: { + body: NewBody, + } + }); + ```