@dominikcz/greg 0.9.27

package/docs/guide/markdown/links-and-toc.md

@@ -0,0 +1,64 @@
+---
+title: Links and TOC
+order: 2
+---
+
+# Links and TOC
+
+## Internal links
+
+Internal links use SPA navigation and update the page without a full reload:
+
+```md
+[Getting Started](../getting-started)
+[API reference](/reference/api)
+[Back to top](#)
+```
+
+Output:
+
+[Getting Started](../getting-started)
+[API reference](/reference/api)
+[Back to top](#)
+
+`.md` and `.html` extensions are stripped automatically.
+
+## Fragment links (same page)
+
+```md
+[See the examples below](#examples)
+```
+
+Output:
+
+[See the examples below](#examples)
+
+Clicking a same-page `#anchor` link scrolls smoothly without a history push.
+
+## External links
+
+External links open via the browser's default navigation.
+
+```md
+[Project website](https://example.com)
+```
+
+Output:
+
+[Project website](https://example.com)
+
+## Table of contents - `[[toc]]`
+
+Insert an inline table of contents at any point in a page:
+
+```md
+[[toc]]
+```
+
+Output:
+
+[[toc]]
+
+By default h2 and h3 headings are included. The right-side **Outline** panel is
+a persistent alternative. See `outline` prop in the
+[`<MarkdownDocs>` reference](/reference/markdowndocs).

package/docs/guide/markdown/math.md

@@ -0,0 +1,54 @@
+---
+title: Math equations
+order: 6
+---
+
+# Math equations
+
+Math rendering via MathJax SVG must be enabled in `svelte.config.js`:
+
+```js
+const gregConfig = {
+  markdown: {
+    math: true,
+  },
+};
+```
+
+Output:
+
+```js
+const gregConfig = {
+  markdown: {
+    math: true,
+  },
+};
+```
+
+## Inline math
+
+```md
+The quadratic formula is $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$.
+```
+
+Output:
+
+Requires `math: true`.
+
+The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$.
+
+## Display math
+
+```md
+$$
+\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
+$$
+```
+
+Output:
+
+Requires `math: true`.
+
+$$
+\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
+$$

package/docs/guide/markdown/syntax-highlighting.md

@@ -0,0 +1,75 @@
+---
+title: Syntax highlighting
+order: 4
+---
+
+## Syntax highlighting
+
+Code blocks are highlighted at build time by [Shiki](https://shiki.style) using
+`github-light` (light mode) and `github-dark` (dark mode):
+
+<<< /__partials/markdown/examples/basic.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/basic.md-->
+
+Supported languages include `javascript`, `typescript`, `bash`, `json`, `html`,
+`css`, `yaml`, `markdown`, `svelte`, `txt`.
+
+## Code highlighting features
+
+Greg supports code highlighting directives in both build-time Shiki output and
+runtime rendering.
+
+| Feature                              | Supported |
+| ------------------------------------ | --------- |
+| Language fence (` ```ts `)           | ✅         |
+| Title in meta (` ```ts [file.ts] `)  | ✅         |
+| Code groups (`::: code-group`)       | ✅         |
+| Highlight lines (` ```ts{2,4} `)     | ✅         |
+| Focused lines (`// [!code focus]`)   | ✅         |
+| Diff markers (`// [!code ++]`, `--`) | ✅         |
+
+Language + title (supported):
+
+<<< /__partials/markdown/examples/language-title.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/language-title.md-->
+
+Line highlighting:
+
+<<< /__partials/markdown/examples/line-highlighting.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/line-highlighting.md-->
+
+Line numbers:
+
+<<< /__partials/markdown/examples/line-numbers.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/line-numbers.md-->
+
+Diff markers:
+
+<<< /__partials/markdown/examples/diff.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/diff.md-->
+
+Focused lines:
+
+<<< /__partials/markdown/examples/focus.md
+
+Output:
+
+<!--@include: /__partials/markdown/examples/focus.md-->
+
+See [Incompatibilities](/incompatibilities) for areas outside code
+highlighting and platform-level differences.

package/docs/guide/routing.md

@@ -0,0 +1,150 @@
+---
+title: Routing
+order: 3
+---
+
+# Routing
+
+## File-based routing
+
+Greg uses **file-based routing**. Every `.md` file inside the `docs/` folder
+becomes a page at the corresponding URL path:
+
+```
+docs/index.md                 →  /
+docs/guide/getting-started.md →  /guide/getting-started
+docs/reference/api.md         →  /reference/api
+```
+
+`index.md` files map to the parent folder URL:
+
+```
+docs/guide/index.md  →  /guide
+```
+
+
+## Partial files
+
+Any file whose name starts with `__` (double underscore) is treated as a
+**partial** — it is excluded from routing and the sidebar, but can be
+included in other pages with the `<!--@include:-->` directive.
+
+```
+docs/guide/__shared-warning.md  ←  not a page, only includable
+```
+
+
+## Sidebar navigation
+
+The sidebar is **generated automatically** from the folder / file structure.
+No manual configuration is required.
+
+Rules:
+- Folders become collapsible section headers.
+- Files become leaf links.
+- Names are capitalised automatically (`getting-started` → `Getting-started`).
+- `index.md` files are attached to their parent folder node.
+- The root `index.md` (`docs/index.md`) is hidden from the sidebar.
+
+### Sidebar link targets
+
+For manual sidebar entries in `greg.config.js`, links respect the `target`
+attribute:
+
+- default is `_self` (same tab)
+- use `target: '_blank'` to open a new tab
+
+```js
+sidebar: [
+  { text: 'Guide', auto: '/guide' },
+  { text: 'GitHub', link: 'https://github.com/dominikcz/greg' }, // _self
+  {
+    text: 'GitHub (new tab)',
+    link: 'https://github.com/dominikcz/greg',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+  },
+]
+```
+
+### Ordering
+
+Items within each level are sorted by the frontmatter `order` field (lower
+values appear first). Items without `order` sort after ordered ones; among
+equal-order items, folders come before leaf pages, then alphabetically by label.
+
+```yaml
+---
+title: Getting Started
+order: 1
+---
+```
+
+Folders use the `order` from their `index.md`:
+
+```yaml
+# docs/guide/index.md
+---
+title: Guide
+order: 2
+---
+```
+
+
+## SPA navigation
+
+Greg is a **single-page application** — navigating between pages never triggers
+a full page reload. Internal links are intercepted and handled by the built-in
+router:
+
+```md
+[Getting Started](./getting-started)           <!-- relative -->
+[API Reference](/reference/api)           <!-- absolute -->
+[Go to anchor](#section-heading)               <!-- same-page anchor -->
+[Other page + anchor](./other#some-section)    <!-- cross-page anchor -->
+```
+
+Both `.md` and `.html` extensions in links are stripped automatically:
+
+```md
+[link](./page.md)    →  navigates to /…/page
+[link](./page.html)  →  navigates to /…/page
+```
+
+External links (starting with `http://`, `https://`, `//`, etc.) open normally
+in the browser.
+
+If a Markdown link (or HTML anchor in Markdown) has an explicit `target`, Greg
+respects it.
+
+
+## `srcDir` prop
+
+The `srcDir` prop of `<MarkdownDocs>` controls docs URL prefix.
+Its default is `/` (root). If your docs are served under a custom prefix,
+pass the new value:
+
+```svelte
+<MarkdownDocs srcDir="/documentation" version="2.0.0" />
+```
+
+The Vite `vitePluginSearchIndex` plug-in must use matching `srcDir` URL prefix:
+
+```js
+// vite.config.js
+vitePluginSearchIndex({ docsDir: 'docs', srcDir: '/documentation' })
+```
+
+
+## 404 behaviour
+
+When a URL matches no Markdown file, the engine displays the folder label as
+a heading and renders any `children` snippet passed to `<MarkdownDocs>`:
+
+```svelte
+<MarkdownDocs srcDir="/" version="1.0.0">
+  {#snippet children()}
+    <p>Select a topic from the sidebar.</p>
+  {/snippet}
+</MarkdownDocs>
+```

package/docs/guide/using-svelte.md

@@ -0,0 +1,88 @@
+---
+title: Using Svelte in Markdown
+order: 4
+---
+
+# Using Svelte in Markdown
+
+Greg processes every `.md` file through [mdsvex](https://mdsvex.pngwn.io/), a
+Markdown preprocessor for Svelte. This means you can mix regular Markdown with
+Svelte components, reactive state and template logic anywhere in your pages.
+
+
+## Auto-imported components
+
+All Greg UI components are automatically available in every Markdown page — no
+`<script>` block needed:
+
+```md
+### Status <Badge type="tip" text="stable" />
+
+<Features features={[
+  { title: 'Fast', details: 'Shiki highlights at build time.' },
+  { title: 'Searchable', details: 'Fuse.js fuzzy search included.' },
+]} />
+```
+
+The following components are always in scope:
+
+`Badge`, `Button`, `Image`, `Link`, `Feature`, `Features`, `Hero`,
+`SocialLink`, `SocialLinks`, `Steps`, `TeamMember`, `TeamMembers`,
+`TeamPage`, `TeamPageTitle`, `TeamPageSection`
+
+
+## Adding a `<script>` block
+
+You can add your own `<script>` block to a page:
+
+```md
+<script>
+  import { onMount } from 'svelte';
+  let now = $state(new Date().toLocaleTimeString());
+  onMount(() => setInterval(() => now = new Date().toLocaleTimeString(), 1000));
+</script>
+
+Current time: **{now}**
+```
+
+> **Note:** mdsvex does not support `<script module>`. Use a plain `<script>`.
+> The `setup` attribute is stripped automatically if present, so copied snippets
+> using that attribute still work.
+
+
+## Template syntax
+
+Standard Svelte template syntax works inside Markdown:
+
+```md
+{#each items as item}
+- {item.name}
+{/each}
+
+{#if showNote}
+> [!NOTE]
+> This note is conditional.
+{/if}
+```
+
+
+## Escaping `{` and `}`
+
+Bare `{…}` expressions in regular Markdown text that are **not** part of Svelte
+syntax may cause parse errors. Escape them with HTML entities:
+
+```md
+Pass an options object like `&#123; key: value &#125;`.
+```
+
+Inside fenced code blocks and backtick inline code, `{` and `}` are escaped
+automatically by the `remarkEscapeSvelte` plugin — no action required.
+
+
+## Limitations
+
+- `<script module>` is not supported inside `.md` files.
+- `<style>` blocks inside `.md` files are processed by Svelte but are scoped to
+  the component — they affect the whole page body.
+- Hot-module replacement works for Markdown content, but adding or removing a
+  file requires a server restart (Vite re-globs the module list).

package/docs/guide/versioning.md

@@ -0,0 +1,281 @@
+---
+title: Versioning
+order: 4
+---
+
+## Overview
+
+Greg supports multi-version documentation builds with two source strategies:
+
+- `branches` (default): reads docs from Git branches/refs
+- `folders`: reads docs from local version directories
+
+Both strategies produce the same final artifact (`<outDir>/__versions/<version>` + `versions.json`).
+After build, Greg also syncs the default version to `dist/` so the root output can be hosted directly.
+The difference is where source docs come from and how reproducible each build is.
+
+`branches` is commit-oriented: each version is tied to a Git ref and resolved to a SHA.
+This is usually best for released docs because output can be reproduced from repository history and branch build cache can speed up repeated runs.
+
+`folders` is workspace-oriented: each version is read from local directories in your current working tree.
+This is usually best when you keep multiple docs trees side-by-side, want quick local iteration, or do not want to depend on Git refs.
+
+### Strategy Philosophy, Pros and Cons
+
+`branches`:
+
+- Pros:
+  - reproducible from Git history (ref -> commit SHA)
+  - good fit for release workflow (`main`, `release/*`, tags)
+  - cache re-use when the same SHA was already built
+- Cons:
+  - requires valid refs and docs content available in those refs
+  - more moving parts (snapshot + branch cache)
+
+`folders`:
+
+- Pros:
+  - simple mental model: build exactly what exists in directories now
+  - very convenient for local development and migration periods
+  - no Git ref resolution required
+- Cons:
+  - output depends on current workspace state (less reproducible by default)
+  - no commit-based cache reuse per version
+
+Recommended choice:
+
+- choose `branches` when docs versions should follow repository history and release refs
+- choose `folders` when docs versions are maintained as separate directory trees in one checkout
+
+## Rules
+
+1. Configure versioning in `greg.config.js` (or `greg.config.ts`) under `versioning`.
+2. Pick one strategy in `versioning.strategy`.
+3. Define version-to-source mapping:
+   - `branches[]`: `version` + `branch`
+   - `folders[]`: `version` + `dir`
+4. Set `default` and optional `aliases` for selector behavior.
+
+## Branch Mode Guide
+
+Use branch mode when each docs version should be built from a Git branch/ref.
+
+Set:
+
+1. `strategy: "branches"`
+2. `branches[]` entries with `version`, `branch`, optional `docsDir`, `title`
+3. `default` and optional `aliases`
+
+Example:
+
+```js [greg.config.js]
+export default {
+  versioning: {
+    strategy: "branches",
+    default: "latest",
+    aliases: {
+      latest: "2.1",
+      stable: "2.0"
+    },
+    branches: [
+      { version: "2.1", branch: "main", title: "2.1" },
+      { version: "2.0", branch: "release/2.0", title: "2.0" }
+    ]
+  }
+};
+```
+
+How versioning works in this mode:
+
+1. For every `branches[]` entry, Greg resolves `branch` to a commit SHA.
+2. Greg creates or reuses a cached docs snapshot for that SHA under `.greg/version-cache/sources/...`.
+3. Greg builds the site for that snapshot (or reuses cached build output for the same SHA).
+4. Greg copies final output to `<outDir>/__versions/<version>`.
+5. After all versions are processed, Greg writes one manifest file to `<outDir>/__versions/versions.json`.
+6. Greg syncs the default version output to `dist/`.
+
+Important: Greg does not checkout branches in your working tree. It reads files directly from Git objects.
+
+## Folder Mode Guide
+
+Use folder mode when each docs version should come from a directory in your working tree.
+
+Set:
+
+1. `strategy: "folders"`
+2. `folders[]` entries with `version`, `dir`, optional `srcDir`, `title`
+3. `default` and optional `aliases`
+
+Example:
+
+```js [greg.config.js]
+export default {
+  versioning: {
+    strategy: "folders",
+    default: "latest",
+    aliases: {
+      latest: "2.1",
+      stable: "2.0"
+    },
+    folders: [
+      { version: "2.1", dir: "./docs", title: "2.1" },
+      { version: "2.0", dir: "./versions/2.0/docs", title: "2.0" }
+    ]
+  }
+};
+```
+
+How versioning works in this mode:
+
+1. For every `folders[]` entry, Greg resolves `dir` to an absolute path.
+2. Greg runs a full Vite build using that directory as docs source.
+3. The temporary build output is copied to `<outDir>/__versions/<version>`.
+4. After all versions are processed, Greg writes `<outDir>/__versions/versions.json`.
+5. Greg syncs the default version output to `dist/`.
+
+Important: in folder mode, each configured version is rebuilt from current local files on each run.
+
+## Commands
+
+Run commands only after config is in place.
+
+Recommended entry point:
+
+```sh
+greg build
+```
+
+If `versioning` is configured, `greg build` automatically runs multi-version build.
+This prevents accidental replacement of versioned output by a single build.
+
+VitePress-compatible defaults in this flow:
+
+- top-level `greg.config.* > outDir` controls where versions are emitted (`<outDir>/__versions`)
+- top-level `greg.config.* > base` is used to derive default manifest URL prefix
+
+Force single-version Vite build (even with versioning configured):
+
+```sh
+greg build --single
+```
+
+Output:
+
+- built sites in `<outDir>/__versions/<version>` (default `dist/__versions/<version>`)
+- manifest in `<outDir>/__versions/versions.json`
+- default version copied to `dist/` for direct hosting
+
+What exactly happens when Greg runs multi-version build (`greg build` with versioning):
+
+1. Greg loads `greg.config.js` or `greg.config.ts` and validates `versioning` schema.
+2. Greg selects strategy (`versioning.strategy`, default `branches`).
+3. Greg prepares working directories: output root (default `<outDir>/__versions`, where `outDir` defaults to `dist`), temporary work root (`.greg/version-build`), and branch cache root (`.greg/version-cache`).
+4. Greg builds each configured version according to strategy.
+5. Greg validates uniqueness of version IDs and validates aliases (`alias -> version`).
+6. Greg resolves default version (configured `default` or first built version).
+7. Greg writes `versions.json` manifest and reports output paths.
+8. Greg copies the default version build to hosting root (`dist/` by default).
+
+What this command changes on disk:
+
+- writes/updates files in `<outDir>/__versions`
+- writes/updates files in `dist` (default version sync)
+- writes/updates internal working data under `.greg/`
+- does not modify your source docs files
+- does not switch your checked out Git branch
+
+Optional maintenance flags:
+
+- `--clean-cache`: removes `.greg/version-cache` before building
+- `--clean-versions`: removes the versioned output directory before building
+- `--rebuild-all`: rebuilds every configured version and skips branch build cache reuse for this run
+
+## UI Components
+
+Greg renders two visual versioning components automatically when a valid manifest is available:
+
+- version switcher in the header
+- outdated-version notice when the current version differs from the default
+
+You can customize labels/messages with `versioning.ui`:
+
+```js [greg.config.js]
+export default {
+  versioning: {
+    ui: {
+      versionMenuLabel: "Version",
+      manifestUnavailableText: "Version selector unavailable",
+      showManifestUnavailableStatus: false,
+      outdatedVersionMessage: "You are viewing an older version ({current}). Recommended: {default}.",
+      outdatedVersionActionLabel: "Go to latest"
+    }
+  }
+};
+```
+
+Supported placeholders in `outdatedVersionMessage`:
+
+- `{current}`
+- `{default}`
+
+### Locale-specific versioning UI
+
+If your site uses locale routes, you can override versioning UI text per locale via `versioning.locales`:
+
+```js [greg.config.js]
+export default {
+  versioning: {
+    locales: {
+      "/": {
+        ui: {
+          versionMenuLabel: "Version"
+        }
+      },
+      "/pl/": {
+        ui: {
+          versionMenuLabel: "Wersja",
+          outdatedVersionActionLabel: "Przejdz do najnowszej"
+        }
+      }
+    }
+  }
+};
+```
+
+Text resolution priority:
+
+1. `versioning.locales[active-locale].ui`
+2. `versioning.ui`
+3. built-in defaults
+
+`showManifestUnavailableStatus` is global-only and must be configured in `versioning.ui`.
+
+## Fallback Behavior
+
+If `versions.json` cannot be loaded:
+
+- Greg hides the selector
+- Greg shows `manifestUnavailableText` in the header only when `showManifestUnavailableStatus` is not `false`
+
+This keeps docs usable even if a deployment serves only a single version.
+
+## Manifest Shape
+
+```json
+{
+  "default": "latest",
+  "versions": [
+    { "version": "2.1", "title": "2.1", "path": "/__versions/2.1/" },
+    { "version": "2.0", "title": "2.0", "path": "/__versions/2.0/" }
+  ],
+  "aliases": {
+    "latest": "2.1",
+    "stable": "2.0"
+  }
+}
+```
+
+`aliases` is a map (`alias -> version`), so alias targets are always unambiguous.
+
+
+