@dominikcz/greg 0.9.27

package/docs/guide/localization.md

@@ -0,0 +1,290 @@
+---
+title: Localization
+order: 3
+---
+
+## Localization
+
+Greg supports locale configuration via `locales` in
+`greg.config.js`. Each locale can define its own labels, navigation, sidebar,
+and translated UI text in `themeConfig`.
+
+## Basic locale map
+
+```js
+export default {
+  srcDir: 'docs',
+  docsBase: '',
+  locales: {
+    '/': {
+      lang: 'en-US',
+      label: 'English',
+      title: 'Greg',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/guide' }],
+        sidebar: [{ text: 'Guide', auto: '/guide' }],
+      },
+    },
+    '/pl/': {
+      lang: 'pl-PL',
+      label: 'Polski',
+      title: 'Greg',
+      themeConfig: {
+        nav: [{ text: 'Przewodnik', link: '/pl/guide' }],
+        sidebar: [{ text: 'Przewodnik', auto: '/guide' }],
+      },
+    },
+  },
+};
+```
+
+For `docsBase: ''`, locale URL mapping is:
+
+- `'/'` -> `/`
+- `'/pl/'` -> `/pl`
+
+## Locale folders and routes
+
+By convention, translated files live in a locale-prefixed folder, for example:
+
+```text
+docs/
+  guide/getting-started.md
+  pl/guide/getting-started.md
+```
+
+That gives:
+
+- EN: `/docs/guide/getting-started`
+- PL: `/docs/pl/guide/getting-started`
+
+Use locale-specific internal links in translated pages to avoid accidental
+`/pl/pl/...` paths.
+
+## Separate directory for each locale
+
+You can also place each locale in its own top-level docs directory.
+
+```js
+export default {
+  srcDir: 'docs',
+  docsBase: '',
+  locales: {
+    '/en/': {
+      lang: 'en-US',
+      label: 'English',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/en/guide' }],
+      },
+    },
+    '/pl/': {
+      lang: 'pl-PL',
+      label: 'Polski',
+      themeConfig: {
+        nav: [{ text: 'Przewodnik', link: '/pl/guide' }],
+      },
+    },
+  },
+};
+```
+
+Recommended content structure:
+
+```text
+docs/
+  en/
+    guide/
+    reference/
+  pl/
+    guide/
+    reference/
+```
+
+That gives URLs such as `/en/...` and `/pl/...`, with fully
+separated content trees per locale.
+
+### Default locale landing behavior
+
+When you use only namespaced locales (for example `'/en/'` and `'/pl/'`, with
+no `'/'` locale), Greg automatically redirects:
+
+- `/` -> first configured locale root (for example `/docs/en`)
+- docs root (for `docsBase: ''` this is `/`) -> first configured locale root
+
+The first entry order in `locales` is therefore treated as the default locale.
+
+How it works:
+
+1. Greg checks whether a root locale `'/'` exists.
+2. If it exists, no redirect is applied.
+3. If it does not exist, and user opens `/` or base docs root, Greg navigates
+   to `locales` first entry root.
+
+Example:
+
+```js
+locales: {
+  '/en/': { label: 'English' },
+  '/pl/': { label: 'Polski' },
+}
+```
+
+In this setup the default landing locale is English, because `'/en/'` is first.
+
+## What goes into `themeConfig`
+
+Each locale can translate standard docs chrome and navigation text:
+
+- `nav`, `sidebar`, `outline`
+- `docFooter.prev`, `docFooter.next`
+- language and accessibility labels (`langMenuLabel`, `skipToContentLabel`, ...)
+- search UI labels via `themeConfig.search.locales`
+
+Example:
+
+```js
+themeConfig: {
+  langMenuLabel: 'Zmien jezyk',
+  returnToTopLabel: 'Wroc do gory',
+  docFooter: { prev: 'Poprzednia strona', next: 'Nastepna strona' },
+  search: {
+    locales: {
+      '/pl/': {
+        button: { buttonText: 'Szukaj...', buttonAriaLabel: 'Wyszukiwarka' },
+        modal: {
+          searchBox: { placeholder: 'Szukaj w dokumentacji...' },
+          noResultsText: 'Brak wynikow dla',
+          loadingScreen: { loadingText: 'Wczytywanie indeksu...' },
+          errorScreen: { titleText: 'Nie udalo sie wczytac indeksu wyszukiwania.' },
+          footer: { navigateText: 'nawiguj', selectText: 'otworz', closeText: 'zamknij' },
+        },
+      },
+    },
+  },
+}
+```
+
+## Search configuration in localized docs
+
+Search behavior is configured in top-level `search`, while locale-specific UI
+texts stay in each locale `themeConfig.search.locales`.
+
+```js
+export default {
+  search: {
+    provider: 'server',
+    serverUrl: '/api/search',
+  },
+  locales: {
+    '/pl/': {
+      themeConfig: {
+        search: {
+          locales: {
+            '/pl/': {
+              button: { buttonText: 'Szukaj...' },
+              modal: { searchBox: { placeholder: 'Szukaj w dokumentacji...' } },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+This keeps one global search backend configuration and per-locale UI copy.
+
+## Versioning localization
+
+Versioning UI text (version switcher and outdated notice) is configured in
+`versioning.ui`, and can be overridden per locale using `versioning.locales`.
+
+```js
+versioning: {
+  ui: {
+    versionMenuLabel: 'Version',
+    outdatedVersionActionLabel: 'Go to latest'
+  },
+  locales: {
+    '/pl/': {
+      ui: {
+        versionMenuLabel: 'Wersja',
+        outdatedVersionActionLabel: 'Przejdz do najnowszej'
+      }
+    }
+  }
+}
+```
+
+Resolution order:
+
+1. `versioning.locales[active-locale].ui`
+2. `versioning.ui`
+3. built-in defaults
+
+If `versions.json` is unavailable, Greg shows the locale-resolved
+`manifestUnavailableText` in the header.
+
+## Built-in locale strings
+
+Greg ships with built-in UI translations for common languages. When a locale
+defines `lang`, Greg automatically resolves the matching built-in strings —
+so you only need to configure what differs from the defaults.
+
+Currently built-in languages:
+
+| `lang` | Language |
+|--------|----------|
+| `en` / `en-US` / `en-GB` … | English |
+| `pl` / `pl-PL` … | Polish |
+
+Built-in strings cover all UI labels: navigation accessibility labels,
+doc footer links, search modal labels, and AI chat labels.
+
+**Resolution order for every UI string:**
+
+1. Explicit value in `themeConfig` / `themeConfig.search.locales`
+2. Built-in string for the locale's `lang`
+3. Hard-coded English fallback
+
+### Minimal multilingual config
+
+With built-in strings you don't need to repeat any UI text. A full
+two-language setup is as simple as:
+
+```js
+export default {
+  locales: {
+    '/': {
+      lang: 'en-US',
+      label: 'English',
+      title: 'My Docs',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/guide' }],
+        sidebar: [{ text: 'Guide', auto: '/guide' }],
+      },
+    },
+    '/pl/': {
+      lang: 'pl-PL',   // ← all Polish UI text is resolved automatically
+      label: 'Polski',
+      title: 'Moja Dokumentacja',
+      themeConfig: {
+        nav: [{ text: 'Przewodnik', link: '/guide' }],
+        sidebar: [{ text: 'Przewodnik', auto: '/guide' }],
+        outline: { level: [2, 3], label: 'Na tej stronie' },
+      },
+    },
+  },
+};
+```
+
+You can still override individual strings by setting them explicitly — the
+explicit value always takes precedence.
+
+## Recommended workflow
+
+1. Start from English docs structure.
+2. Mirror file paths in `docs/pl/...`.
+3. Translate page content.
+4. Translate navigation and labels in locale `themeConfig`.
+5. Build and verify routes/search for both locales.

package/docs/guide/markdown/code.md

@@ -0,0 +1,95 @@
+---
+title: Code blocks and groups
+order: 5
+---
+
+# Code blocks and groups
+
+For syntax highlighting details and line focus/diff markers, see
+[Syntax highlighting](./syntax-highlighting).
+
+## Code block title
+
+Add a `[Title]` annotation in the language line:
+
+````md
+```js [example.js]
+export const answer = 42;
+```
+````
+
+Output:
+
+```js [example.js]
+export const answer = 42;
+```
+
+## Code groups
+
+Group multiple code blocks into a tabbed interface:
+
+````md
+::: code-group
+
+```sh [npm]
+npm install
+```
+
+```sh [pnpm]
+pnpm install
+```
+
+```sh [yarn]
+yarn install
+```
+
+:::
+````
+
+Output:
+
+::: code-group
+
+```sh [npm]
+npm install
+```
+
+```sh [pnpm]
+pnpm install
+```
+
+```sh [yarn]
+yarn install
+```
+
+:::
+
+Explicit label override:
+
+````md
+::: code-group labels=[Option A, Option B]
+
+```js
+// option A
+```
+
+```ts
+// option B
+```
+
+:::
+````
+
+Output:
+
+::: code-group labels=[Option A, Option B]
+
+```js
+// option A
+```
+
+```ts
+// option B
+```
+
+:::

package/docs/guide/markdown/components-and-mermaid.md

@@ -0,0 +1,43 @@
+---
+title: Svelte components and Mermaid
+order: 8
+---
+
+# Svelte components and Mermaid
+
+## Svelte components
+
+Built-in components (`Badge`, `Button`, `Image`, `Link`) can be used directly in
+`.md` files without any import statement:
+
+```md
+### Stability <Badge type="tip" text="stable" />
+
+The API is considered stable as of v1.0.
+
+<Badge type="warning">experimental</Badge>
+```
+
+Output:
+
+**Stability** <Badge type="tip" text="stable" />
+
+The API is considered stable as of v1.0.
+
+<Badge type="warning">experimental</Badge>
+
+::: info .svx files
+In `.svx` files you can also write arbitrary Svelte markup with full reactivity
+(`$state`, event handlers, etc.). In runtime `.md` files only the registered
+built-in components are hydrated.
+:::
+
+## Mermaid diagrams
+
+Greg supports Mermaid diagrams.
+
+<<< @/snippets/mermaid-sequence.md
+
+Output:
+
+<!--@include: @/snippets/mermaid-sequence.md-->

package/docs/guide/markdown/containers.md

@@ -0,0 +1,110 @@
+---
+title: Custom containers
+order: 3
+---
+
+# Custom containers
+
+## Default types
+
+```md
+::: info
+Informational note.
+:::
+
+::: tip
+Helpful tip.
+:::
+
+::: warning
+Watch out for this.
+:::
+
+::: danger
+Dangerous operation!
+:::
+```
+
+Output:
+
+::: info
+Informational note.
+:::
+
+::: tip
+Helpful tip.
+:::
+
+::: warning
+Watch out for this.
+:::
+
+::: danger
+Dangerous operation!
+:::
+
+## Custom title
+
+```md
+::: warning Be careful!
+Custom title replaces the default label.
+:::
+```
+
+Output:
+
+::: warning Be careful!
+Custom title replaces the default label.
+:::
+
+## Details (collapsible)
+
+```md
+::: details Click to expand
+Hidden content revealed on click.
+:::
+```
+
+Output:
+
+::: details Click to expand
+Hidden content revealed on click.
+:::
+
+## GitHub-style alerts
+
+The `> [!TYPE]` blockquote syntax is also supported:
+
+```md
+> [!NOTE]
+> Useful information.
+
+> [!TIP]
+> Pro tip.
+
+> [!IMPORTANT]
+> Key point.
+
+> [!WARNING]
+> Be careful.
+
+> [!CAUTION]
+> Dangerous action.
+```
+
+Output:
+
+> [!NOTE]
+> Useful information.
+
+> [!TIP]
+> Pro tip.
+
+> [!IMPORTANT]
+> Key point.
+
+> [!WARNING]
+> Be careful.
+
+> [!CAUTION]
+> Dangerous action.

package/docs/guide/markdown/header-anchors.md

@@ -0,0 +1,34 @@
+---
+title: Header anchors
+order: 1
+---
+
+# Header anchors
+
+Every heading automatically receives a slug-based `id` so it can be linked to:
+
+```md
+## My Section
+```
+
+Output:
+
+## My Section
+
+Expected HTML includes `<h2 id="my-section">`.
+
+## Custom anchors
+
+Override the auto-generated slug with a `{#custom-id}` suffix:
+
+```md
+## My Section {#custom-anchor}
+```
+
+This lets you link to `#custom-anchor` even if the heading text changes.
+
+Output:
+
+## My Section {#custom-anchor}
+
+[Jump to custom anchor](#custom-anchor)

package/docs/guide/markdown/includes.md

@@ -0,0 +1,84 @@
+---
+title: Including external files
+order: 5
+---
+
+# Including external files
+
+## Code snippets - `<<<`
+
+Import an external source file as a code block:
+
+```md
+<<< @/snippets/example.js
+```
+
+Output:
+
+<<< @/snippets/example.js
+
+The `@` alias resolves to the project root. The language is detected from the
+file extension.
+
+### Region
+
+Import only a named region of the file (marked with `#region name` / `#endregion`):
+
+```md
+<<< @/snippets/example.js#setup
+```
+
+Output:
+
+<<< @/snippets/example.js#setup
+
+### Range
+
+Import specific line numbers:
+
+```md
+<<< @/snippets/example.js{5-10}
+```
+
+Output:
+
+<<< @/snippets/example.js{5-10}
+
+### Title override
+
+```md
+<<< @/snippets/example.js [my-example.js]
+```
+
+Output:
+
+<<< @/snippets/example.js [my-example.js]
+
+## Markdown include - `<!--@include:-->`
+
+Include another Markdown file inline:
+
+```md
+<!--@include: /guide/__shared-warning.md-->
+```
+
+File `__shared-warning.md` looks like this:
+
+<<< /guide/__shared-warning.md
+
+Output:
+
+<!--@include: /guide/__shared-warning.md-->
+
+The included file is processed by the full Markdown pipeline. Partial files
+(name starts with `__`) are excluded from routing.
+
+The `/` prefix resolves to the `docs/` directory root:
+
+```md
+<!--@include: /__partials/note.md-->
+```
+
+Output:
+
+<!--@include: /__partials/note.md-->

package/docs/guide/markdown/index.md

@@ -0,0 +1,20 @@
+---
+title: Markdown Extensions
+order: 2
+---
+
+# Markdown Extensions
+
+Greg extends standard Markdown with a rich set of authoring features.
+
+## Topics
+
+- [Header anchors](./header-anchors)
+- [Links and table of contents](./links-and-toc)
+- [Custom containers](./containers)
+- [Syntax highlighting](./syntax-highlighting)
+- [Code blocks and code groups](./code)
+- [Including external files](./includes)
+- [Math equations](./math)
+- [Inline attributes on links and images](./inline-attributes)
+- [Svelte components and Mermaid](./components-and-mermaid)

package/docs/guide/markdown/inline-attributes.md

@@ -0,0 +1,21 @@
+---
+title: Inline attributes
+order: 7
+---
+
+# Inline attributes on links and images
+
+Attach HTML attributes to links and images with a `{...}` block immediately after
+the closing `)`:
+
+```md
+[Open in new tab](https://example.com){target="_blank" rel="noopener"}
+
+[styled link](../routing){class="my-link"}
+```
+
+Output:
+
+[Open in new tab](https://example.com){target="_blank" rel="noopener"}
+
+[styled link](../routing){class="my-link"}