@dominikcz/greg 0.9.27

package/docs/reference/markdowndocs.md

@@ -0,0 +1,275 @@
+---
+title: MarkdownDocs Component
+---
+
+`MarkdownDocs` is the top-level component that wires together the entire
+documentation engine: routing, sidebar navigation, the outline panel, search,
+dark/light mode and Carbon Ads.
+
+Mount it in `src/App.svelte`:
+
+```svelte
+<script>
+    import MarkdownDocs from '@dominikcz/greg'
+</script>
+
+<MarkdownDocs srcDir="/" version="1.0.0" />
+```
+
+
+## Props
+
+### `locales` (via `greg.config.js`)
+
+- **Type:** `Record<string, LocaleConfig>`
+- **Location:** `greg.config.js` (not a direct `<MarkdownDocs>` prop)
+
+Localization is supported through `greg.config.js`:
+
+- locale keys like `'/'`, `'/pl/'`
+- locale-specific `lang`, `title`
+- optional locale `label` used in header language switcher
+- locale-specific `themeConfig` keys:
+  `nav`, `sidebar`, `outline`, `lastUpdatedText`, `langMenuLabel`,
+  `sidebarMenuLabel`, `skipToContentLabel`, `returnToTopLabel`,
+  `darkModeSwitchLabel`, `lightModeSwitchTitle`, `darkModeSwitchTitle`,
+  `docFooter`, `siteTitle`, `logo`, `socialLinks`, `editLink`, `footer`, `aside`, `lastUpdated`
+
+Language switcher behavior:
+
+- appears in the header when two or more locales are defined
+- with `i18nRouting: true` (default), preserves current relative page across locales
+- with `i18nRouting: false`, switches directly to locale root
+- falls back to target locale root when the mapped page does not exist
+
+Locale paths are resolved under `srcDir`:
+
+- if `srcDir = '/docs'`
+- locale `'/'` maps to `'/docs'`
+- locale `'/pl/'` maps to `'/docs/pl'`
+
+```js
+export default {
+<MarkdownDocs srcDir="/" version="1.0.0" />
+  i18nRouting: true,
+  locales: {
+    '/': {
+      lang: 'en-US',
+      title: 'Docs',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/docs/guide' }],
+        sidebar: [{ text: 'Guide', auto: '/guide' }],
+        outline: [2, 3],
+        lastUpdatedText: 'Last updated:',
+        langMenuLabel: 'Change language',
+        sidebarMenuLabel: 'Menu',
+        skipToContentLabel: 'Skip to content',
+        returnToTopLabel: 'Return to top',
+        darkModeSwitchLabel: 'Appearance',
+        lightModeSwitchTitle: 'Switch to light theme',
+        darkModeSwitchTitle: 'Switch to dark theme',
+        docFooter: { prev: 'Previous', next: 'Next' },
+  srcDir: 'docs',
+  docsBase: '',
+    },
+    '/pl/': {
+      lang: 'pl-PL',
+      label: 'Polski',
+      title: 'Dokumentacja',
+      themeConfig: {
+        nav: [{ text: 'Guide', link: '/guide' }],
+        sidebar: [{ text: 'Przewodnik', auto: '/pl/guide' }],
+        outline: { level: [2, 3], label: 'Na tej stronie' },
+        lastUpdatedText: 'Zaktualizowano:',
+        langMenuLabel: 'Zmien jezyk',
+        sidebarMenuLabel: 'Menu',
+        skipToContentLabel: 'Przejdz do tresci',
+        returnToTopLabel: 'Wroc na gore',
+        darkModeSwitchLabel: 'Wyglad',
+        lightModeSwitchTitle: 'Przelacz na jasny motyw',
+        darkModeSwitchTitle: 'Przelacz na ciemny motyw',
+        docFooter: { prev: 'Poprzednia', next: 'Nastepna' },
+      },
+    },
+  },
+}
+```
+
+### `srcDir`
+        nav: [{ text: 'Przewodnik', link: '/pl/guide' }],
+- **Type:** `string`
+- **Default:** `"/docs"`
+
+URL prefix that maps to the `docs/` folder. Must match the `srcDir` value
+passed to `vitePluginSearchIndex` in `vite.config.js`.
+
+```svelte
+<MarkdownDocs srcDir="/documentation" version="1.0.0" />
+```
+
+### `version`
+
+- **Type:** `string`
+- **Default:** `""`
+
+Version string displayed as a badge next to the site title in the header.
+Pass the package version via Vite's `define`:
+
+```svelte
+<!-- Assuming __VERSION__ is defined in vite.config.js -->
+<MarkdownDocs srcDir="/" version={__VERSION__} />
+```
+URL prefix used by `<MarkdownDocs>` routing.
+In `greg.config.*` use top-level `docsBase` for this value.
+Top-level `srcDir` is the physical docs folder (e.g. `docs`).
+### `mainTitle`
+
+- **Type:** `string`
+- **Default:** `"Greg"`
+
+Name of the project shown in the top-left header.
+
+```svelte
+<MarkdownDocs srcDir="/" version="1.0.0" mainTitle="My Project" />
+```
+
+### `outline`
+
+- **Type:** `false | number | [number, number] | 'deep' | { level?: …, label?: string }`
+- **Default:** `[2, 3]`
+<MarkdownDocs srcDir="/" version={__VERSION__} />
+Controls the right-side **Outline** (on-this-page) panel.
+
+| Value                                 | Effect                             |
+| ------------------------------------- | ---------------------------------- |
+| `false`                               | Outline panel is hidden            |
+| `2`                                   | Only `h2` headings                 |
+| `[2, 3]`                              | `h2` and `h3` headings *(default)* |
+| `'deep'`                              | `h2` through `h6`                  |
+| `{ level: [2,4], label: 'Contents' }` | Custom range and panel label       |
+
+<MarkdownDocs srcDir="/" version="1.0.0" mainTitle="My Project" />
+<MarkdownDocs srcDir="/" version="1.0.0" outline="deep" />
+```
+
+### `carbonAds`
+
+- **Type:** `{ code: string; placement: string } | undefined`
+- **Default:** `undefined`
+
+Displays a [Carbon Ads](https://www.carbonads.net/) block in the outline sidebar.
+See the [Carbon Ads reference](/reference/carbon-ads) for details.
+
+```svelte
+<MarkdownDocs
+  srcDir="/"
+  version="1.0.0"
+  carbonAds={{ code: 'CWYD42JW', placement: 'myprojectdev' }}
+/>
+```
+
+### `children`
+
+- **Type:** `Snippet | undefined`
+
+Rendered when the active path does not match any Markdown file (i.e., when a
+folder URL has no `index.md`). Useful for a custom landing splash or a
+"choose a topic" prompt.
+
+```svelte
+<MarkdownDocs srcDir="/" version="1.0.0">
+  {#snippet children()}
+    <p>👉 Select a page from the sidebar to get started.</p>
+  srcDir="/"
+</MarkdownDocs>
+```
+
+
+## Vite configuration
+
+`vitePluginSearchIndex` must be added to `vite.config.js` to build the
+full-text search index:
+
+```js
+// vite.config.js
+import { vitePluginSearchIndex } from '@dominikcz/greg/plugins';
+
+export default defineConfig({
+  plugins: [
+    svelte(),
+    vitePluginSearchIndex({ docsDir: 'docs', srcDir: '/' }),
+  ],
+  resolve: {
+    alias: {
+      '$components': resolve('./src/lib/components'),
+    },
+  },
+});
+```
+
+| Option     | Description                                                        |
+| ---------- | ------------------------------------------------------------------ |
+| `docsDir`  | Folder name relative to the project root that contains `.md` files |
+| `srcDir` | URL prefix — must match the `srcDir` prop                        |
+
+
+## svelte.config.js
+    vitePluginSearchIndex({ docsDir: 'docs', srcDir: '/' }),
+The markdown pipeline is configured in `svelte.config.js`. The `gregConfig`
+object at the top of the file exposes user-facing options:
+
+```js
+const gregConfig = {
+  markdown: {
+    math: false,   // set to true to enable $…$ / $$…$$ rendering via MathJax
+  },
+};
+```
+
+## Runtime extension model
+
+`MarkdownRenderer.svelte` now delegates registry-style extension points to
+`src/lib/MarkdownDocs/markdownRendererRuntime.ts` instead of keeping hardcoded
+branches inline. This keeps runtime rendering predictable and makes new
+features easier to add.
+
+### 1) Component hydration registry
+
+`COMPONENT_REGISTRY` maps a tag name to:
+
+- a Svelte `component`
+- a `buildProps(el)` function
+
+This is used for custom component tags like `badge`, `button`, `image`,
+`link`, and `codegroup`.
+
+### 2) Markdown plugin registries
+
+The markdown pipeline is assembled from two ordered registries:
+
+- `getRemarkPluginEntries(baseUrl, docsPrefix)`
+- `getRehypePluginEntries()`
+
+These cover, among others:
+
+- custom containers (`remarkContainers` + `rehypeContainers`)
+- code blocks (`rehypeShiki`, `rehypeCodeTitle`, `rehypeCodeGroup`)
+- Mermaid preprocessing (`rehypeMermaid`)
+- Steps normalization (`rehypeStepsWrapper`)
+- headings/TOC (`rehypeSlug`, `rehypeAutolinkHeadings`, `rehypeTocPlaceholder`)
+
+### 3) Render handlers (post-HTML stage)
+
+After HTML is rendered, handlers are executed from ordered lists:
+
+- `RUNTIME_RENDER_HANDLERS` (full render pass)
+- `THEME_CHANGE_RENDER_HANDLERS` (theme-only pass)
+
+Current handlers include component hydration and Mermaid initialization/re-render.
+
+## What to extend where
+
+- Use **component registry** for interactive widgets rendered from custom tags.
+- Use **rehype/remark registries** for static HTML transforms.
+- Use **render handlers** for browser-only work that needs live DOM access
+  (for example diagram engines).

package/docs/reference/outline.md

@@ -0,0 +1,79 @@
+---
+title: Outline
+---
+
+# Outline (On This Page)
+
+The **Outline** panel is shown in the right column of every doc page. It displays
+a scrollspy-aware list of headings for the current page and lets the reader jump
+to any section.
+
+
+## Configuring the outline
+
+Pass the `outline` prop to `<MarkdownDocs>`:
+
+```svelte
+<!-- Show h2 and h3 (default) -->
+<MarkdownDocs srcDir="/" version="1.0.0" outline={[2, 3]} />
+
+<!-- Show all headings -->
+<MarkdownDocs srcDir="/" version="1.0.0" outline="deep" />
+
+<!-- Show only h2 -->
+<MarkdownDocs srcDir="/" version="1.0.0" outline={2} />
+
+<!-- Disable -->
+<MarkdownDocs srcDir="/" version="1.0.0" outline={false} />
+
+<!-- Custom label + range -->
+<MarkdownDocs
+  srcDir="/"
+  version="1.0.0"
+  outline={{ level: [2, 4], label: 'Contents' }}
+/>
+```
+
+### Accepted values
+
+| Value              | Effect                                                                          |
+| ------------------ | ------------------------------------------------------------------------------- |
+| `false`            | Outline panel is hidden                                                         |
+| `number`           | Only that heading level (e.g. `2` → h2 only)                                    |
+| `[min, max]`       | Range of heading levels, e.g. `[2, 3]`                                          |
+| `'deep'`           | Same as `[2, 6]`                                                                |
+| `{ level, label }` | Object form — `level` follows the rules above; `label` overrides "On this page" |
+
+
+## Scrollspy behaviour
+
+The active link in the outline is updated as the user scrolls. A heading is
+considered "active" when it reaches within 72 px of the top of the content pane.
+
+The outline is built by scanning the live DOM with a `MutationObserver`, so it
+correctly reflects the final rendered content including async-loaded pages.
+
+
+## Inline `[[toc]]`
+
+You can also insert a static **inline** table of contents at any point inside a
+page with the `[[toc]]` placeholder:
+
+```md
+## Contents
+
+[[toc]]
+```
+
+By default it includes h2 and h3. This is independent of the right-side Outline
+panel — both can be used together.
+
+
+## CSS variables
+
+| Variable                | Default (light) | Description                |
+| ----------------------- | --------------- | -------------------------- |
+| `--greg-toc-background` | `transparent`   | Panel background           |
+| `--greg-toc-color`      | `#3d3d3d`       | Section label colour       |
+| `--greg-toc-link-color` | `#4a4a6a`       | Link colour                |
+| `--greg-toc-link-hover` | `#646cff`       | Link hover / active colour |

package/docs/reference/search.md

@@ -0,0 +1,263 @@
+---
+title: Search
+---
+
+Greg includes a built-in full-text search powered by [Fuse.js](https://fusejs.io/).
+No external service or API key is required.
+
+
+## Search modes
+
+Search mode is configured in `greg.config.js`:
+
+```js
+search: {
+  provider: 'server', // 'server' | 'local' | 'none'
+  // serverUrl: '/api/search'
+}
+```
+
+- `server`: Browser calls `GET /api/search?q=...` and receives ready-ranked results. Recommended for large doc sets (best default).
+- `local`: Browser downloads `/search-index.json` and runs Fuse.js locally. Recommended for small doc sets.
+- `none`: Built-in search UI (button + modal + shortcuts) is disabled. Recommended for sites without built-in search.
+
+
+## How indexing works
+
+At **build time**, `vitePluginSearchIndex` walks every `.md` file in the docs
+folder, strips Markdown syntax, splits each page into sections (by heading) and
+emits a `/search-index.json` file into the Vite output.
+
+At **run time**:
+
+- in `local` mode, the modal fetches `/search-index.json` and searches in-browser,
+- in `server` mode, the modal queries your configured `serverUrl` endpoint.
+
+
+## Required Vite plugins
+
+Use both plugins in `vite.config.js`:
+
+```js
+import { vitePluginSearchIndex, vitePluginSearchServer } from '@dominikcz/greg/plugins';
+
+export default defineConfig({
+  plugins: [
+    svelte(),
+    vitePluginSearchIndex({ docsDir: 'docs', srcDir: '/' }),
+    vitePluginSearchServer({ docsDir: 'docs', srcDir: '/' }),
+  ],
+});
+```
+
+`vitePluginSearchServer` exposes `/api/search` automatically in both `dev` and
+`preview`.
+
+
+## Production server-side search
+
+Build your site first:
+
+```bash
+npm run build
+```
+
+Then start the standalone search server:
+
+```bash
+greg search-server --index dist/search-index.json --port 3100
+```
+
+Set `serverUrl` to that endpoint, for example:
+
+```js
+search: {
+  provider: 'server',
+  serverUrl: 'http://localhost:3100/api/search'
+}
+```
+
+In production, you will usually place the search server behind a reverse proxy
+so your frontend can keep using `/api/search`.
+
+
+## Custom search engine
+
+If you want Algolia, Meilisearch, Typesense, or your own backend:
+
+- set `provider: 'none'` in `greg.config.js`,
+- pass `searchProvider` prop to `<MarkdownDocs>`.
+
+With `searchProvider` provided, Greg enables the Search button/modal again and
+routes queries through your function.
+
+`searchProvider` signature:
+
+```ts
+(query: string, limit?: number) => Promise<SearchResult[]>
+```
+
+Expected `SearchResult` shape:
+
+```ts
+type SearchResult = {
+  id: string;
+  title: string;
+  titleHtml: string;
+  sectionTitle: string;
+  sectionTitleHtml?: string; // optional but recommended for consistent heading highlights
+  sectionAnchor: string;
+  excerptHtml: string;
+  score: number;
+}
+```
+
+`sectionTitleHtml` is now used by the built-in modal to render heading highlights.
+If missing, Greg falls back to escaped `sectionTitle` (without match-aware markup).
+
+
+## Opening search
+
+| Method                                     | Action      |
+| ------------------------------------------ | ----------- |
+| Click the **Search…** button in the header | Opens modal |
+| `Ctrl + K`                                 | Opens modal |
+| `Cmd + K` (macOS)                          | Opens modal |
+
+
+## Keyboard navigation inside the modal
+
+| Key       | Action                        |
+| --------- | ----------------------------- |
+| `↑` / `↓` | Select previous / next result |
+| `Enter`   | Navigate to selected result   |
+| `Esc`     | Close modal                   |
+
+
+## Search ranking
+
+Results are scored by Fuse.js using weighted fields:
+
+| Field             | Weight |
+| ----------------- | ------ |
+| Page title        | 3×      |
+| Section heading   | 2×      |
+| Section body text | 1×      |
+
+A fuzzy threshold of `0.4` is used — tighter than the default, so only genuine
+matches surface. `ignoreLocation: true` means the match can appear anywhere in
+the text, not just at the start.
+
+
+## Excluding pages from the index
+
+Files whose names start with `__` (double underscore) are automatically excluded
+from both routing and the search index.
+
+
+## Limitations
+
+- In `local` mode, large indices can significantly increase initial payload size
+  and memory usage in the browser.
+- In `server` mode, your search endpoint must be reachable from the client
+  (`serverUrl` must be correct for your environment).
+- Code block content is stripped from the index (not searchable).
+
+
+## AI knowledge base
+
+The AI feature adds an **Ask AI** tab to the search modal. It uses a retrieval-augmented
+generation (RAG) pipeline: your docs are chunked and embedded at build time, then the
+top matching chunks are injected as context into each LLM call.
+
+Enable it in `greg.config.js`:
+
+```js
+search: {
+  ai: {
+    enabled: true,
+    provider: 'ollama', // or 'openai'
+    ollama: { model: 'phi4' },
+  }
+}
+```
+
+See the [Getting started guide](/docs/guide/getting-started) for the required Vite plugin
+(`vitePluginAiServer`) and the production AI server setup.
+
+
+### AI characters (personas)
+
+Greg ships five built-in personas that users can pick in the chat UI:
+
+| ID             | Name         | Icon | Description                        |
+| -------------- | ------------ | ---- | ---------------------------------- |
+| `professional` | Professional | 👔   | Precise, formal, technical answers |
+| `friendly`     | Friendly     | 😊   | Warm, approachable explanations    |
+| `pirate`       | Pirate       | 🏴‍☠️   | Arr! Knowledge on the high seas!   |
+| `sensei`       | Sensei       | 🥋   | Patient teacher, step-by-step      |
+| `concise`      | Concise      | ✂️   | Maximum density, minimum words     |
+
+#### Limiting which characters are available
+
+Pass an array of IDs to show only a subset:
+
+```js
+ai: {
+  characters: ['professional', 'friendly', 'concise'],
+}
+```
+
+An empty array (or omitting the key) makes all five characters available.
+
+#### Setting the default character
+
+```js
+ai: {
+  defaultCharacter: 'friendly',
+}
+```
+
+If omitted, `'professional'` is selected by default.
+
+#### Defining custom characters
+
+Add your own personas via `customCharacters`.
+A custom entry with the same `id` as a built-in will **override** the built-in.
+
+```js
+import { aiCharacters } from '@dominikcz/greg/plugins';
+
+ai: {
+  // You can reference built-in character IDs via the exported aiCharacters array.
+  // console.log(aiCharacters.map(c => c.id));
+
+  customCharacters: [
+    {
+      id: 'mybot',
+      name: 'My Bot',
+      icon: '🤖',
+      description: 'Tailored assistant for this project',
+      systemPrompt: 'You are a helpful assistant specialized in this project. Always respond in the same language as the user\'s question.',
+    },
+  ],
+  // Optionally restrict to only your custom character plus one built-in:
+  characters: ['professional', 'mybot'],
+}
+```
+
+`customCharacters` is merged with the built-in list before the `characters` filter is applied.
+The `aiCharacters` export is provided for reference — you can inspect built-in IDs or
+re-use/extend built-in system prompts programmatically.
+
+`AiCharacterConfig` type (from `@dominikcz/greg/types`):
+
+```ts
+type AiCharacterConfig = {
+  id: string;
+  name: string;
+  icon: string;
+  description?: string;
+  systemPrompt: string;
+};
+```