@dominikcz/greg 0.9.27

package/docs/incompatibilities.md

@@ -0,0 +1,48 @@
+---
+title: VitePress Incompatibilities
+order: 999
+---
+
+Greg is strongly inspired by [VitePress](https://vitepress.dev){target="_blank"} and reuses most
+Markdown conventions. This page lists **only differences and gaps**. If a feature
+is not mentioned here, behavior should be considered equivalent.
+
+## Compatibility status
+
+Greg is **compatible with VitePress at configuration level** for the supported docs/theme options
+(including locale config).
+
+Current incompatibilities are mostly about **runtime API** and **platform features**, not config.
+
+
+## Why Greg is different
+
+Greg is optimized for **very large documentation projects** and fast SPA runtime navigation.
+Its architecture is built around preprocessed metadata (`virtual:greg-frontmatter`),
+predictable routing/sidebar generation, and search modes designed for large content sets.
+
+Because of that focus, not every VitePress API/platform feature is mirrored 1:1.
+These differences are intentional trade-offs, not config-level gaps.
+
+For architecture and design assumptions, see:
+
+- [MarkdownDocs Component](/reference/markdowndocs)
+- [Search](/reference/search)
+
+
+## Summary
+
+| Area | Status |
+| --- | --- |
+| Config compatibility | ✅ VitePress-like config supported in `greg.config.js` |
+| Runtime API parity | ❌ No full VitePress API parity (`useData`, `useRouter`, `withBase`, `*.data.*`) |
+| Platform features | ⚠️ Separate track (for example: sitemap, SSG adapters, build/deploy capabilities) |
+| Rendering model | Greg is SPA-first, VitePress is SSG-first |
+| Top navigation | ✅ Config-compatible; Greg supports deeper dropdown nesting |
+| Markdown component model | Different by design: Greg supports Svelte in Markdown, VitePress supports Vue |
+
+
+## Deployment note
+
+Because Greg is SPA-first, configure your server to rewrite routes to `index.html`
+(see [Deploying](/guide/deploying)).

package/docs/index.md

@@ -0,0 +1,43 @@
+---
+layout: home
+title: Greg
+order: 0
+
+hero:
+  name: Greg
+  text: Svelte-powered documentation engine
+  tagline: Write Markdown, get beautiful documentation — hot-reloaded in milliseconds.
+  image:
+    light: /greg-logo-light.svg
+    dark: /greg-logo-dark.svg
+    alt: Greg logo
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /guide/getting-started
+    - theme: alt
+      text: Markdown Reference
+      link: /guide/markdown
+
+features:
+  - icon: 📝
+    title: Markdown-first
+    details: Write docs in plain Markdown, enhanced with custom containers, code groups, math and more.
+  - icon: ⚡
+    title: Vite-powered
+    details: Instant server start, lightning-fast HMR, and full access to the Vite plug-in ecosystem.
+  - icon:
+      src: /svelte.svg
+      alt: Svelte
+    title: Built with Svelte 5
+    details: Use Svelte components directly inside Markdown pages. Runes-based reactivity throughout.
+  - icon: 🔍
+    title: Built-in search
+    details: Full-text fuzzy search powered by Fuse.js — no external service required.
+  - icon: 🌗
+    title: Dark / light mode
+    details: Automatic theme detection with manual override, persisted in localStorage.
+  - icon: 🧭
+    title: Auto navigation
+    details: Sidebar and routing are generated automatically from the docs folder structure.
+---

package/docs/reference/badge.md

@@ -0,0 +1,100 @@
+---
+title: Badge
+---
+
+# Badge
+
+The `Badge` component adds an inline status label to headings or any inline content.
+
+## Usage
+
+`Badge` supports two authoring styles:
+
+- Markdown inline usage (`<Badge ... />`) in docs pages
+- Direct component usage in `.svelte` files
+
+### Markdown inline usage
+
+`Badge` is available in every Markdown page without an import:
+
+```md
+### Title <Badge type="info" text="default" />
+### Title <Badge type="tip" text="stable" />
+### Title <Badge type="warning" text="beta" />
+### Title <Badge type="danger" text="deprecated" />
+```
+
+**Output:**
+
+### Title <Badge type="info" text="default" />
+### Title <Badge type="tip" text="stable" />
+### Title <Badge type="warning" text="beta" />
+### Title <Badge type="danger" text="deprecated" />
+
+### Direct component usage (`.svelte`)
+
+```svelte
+<script>
+  import Badge from '$components/Badge.svelte';
+</script>
+
+<h3>
+  Title <Badge type="tip" text="stable" />
+</h3>
+```
+
+**Output:**
+
+Equivalent inline status badge rendered next to heading text.
+
+
+## Custom children
+
+Pass content as children instead of using the `text` prop:
+
+```md
+### Title <Badge type="info">custom content</Badge>
+```
+
+### Title <Badge type="info">custom content</Badge>
+
+
+## Props
+
+```ts
+interface Props {
+  /** Text to display. Ignored when children are provided. */
+  text?: string;
+
+  /** Badge colour variant. Defaults to 'tip'. */
+  type?: 'info' | 'tip' | 'warning' | 'danger';
+
+  /** Svelte snippet — overrides `text`. */
+  children?: Snippet;
+}
+```
+
+
+## CSS variables
+
+Customise badge colours by overriding Greg's CSS variables:
+
+```css
+:root {
+  --greg-info-border: transparent;
+  --greg-info-text:   var(--greg-accent);
+  --greg-info-bg:     rgba(100, 108, 255, 0.08);
+
+  --greg-tip-border:  transparent;
+  --greg-tip-text:    #2d9e68;
+  --greg-tip-bg:      rgba(66, 184, 131, 0.08);
+
+  --greg-warning-border: transparent;
+  --greg-warning-text:   #7d4e00;
+  --greg-warning-bg:     rgba(201, 126, 10, 0.08);
+
+  --greg-danger-border: transparent;
+  --greg-danger-text:   #c81d1d;
+  --greg-danger-bg:     rgba(224, 82, 82, 0.08);
+}
+```

package/docs/reference/carbon-ads.md

@@ -0,0 +1,46 @@
+---
+title: Carbon Ads
+---
+
+# Carbon Ads
+
+Greg supports [Carbon Ads](https://www.carbonads.net/) natively. When configured,
+an ad unit is displayed at the bottom of the right-side Outline panel.
+
+
+## Configuration
+
+Pass the `carbonAds` prop to `<MarkdownDocs>`:
+
+```svelte
+<MarkdownDocs
+  srcDir="/"
+  version="1.0.0"
+  carbonAds={{ code: 'CWYD42JW', placement: 'myprojectdev' }}
+/>
+```
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `code`      | `string` | Your Carbon Ads `serve` code   |
+| `placement` | `string` | Your Carbon Ads placement name |
+
+
+## Behaviour
+
+- The Carbon Ads script is injected once on `onMount`.
+- On every SPA navigation, `_carbonads.refresh()` is called automatically so the
+  ad unit updates for the new page context.
+- If `carbonAds` is not provided (the default), no script is injected and the
+  Outline panel right edge is not shown.
+
+
+## Styling
+
+Carbon Ads renders inside a `.CarbonAds` container. Override the appearance with:
+
+```css
+:root {
+  --greg-carbon-ads-bg-color: #f0f0f4;   /* falls back to --greg-menu-background */
+}
+```

package/docs/reference/code-group.md

@@ -0,0 +1,126 @@
+---
+title: Code Group
+---
+
+# Code Group
+
+`Code Group` lets you present multiple related code snippets as tabs.
+Use it when you want to show equivalent commands for different tools
+or languages in one compact block.
+
+## Usage
+
+`Code Group` supports two authoring styles:
+
+- Markdown directive syntax (`::: code-group ... :::`)
+- Component-tag syntax (`<CodeGroup ... />`)
+
+### Markdown directive syntax
+
+Write a `::: code-group` container and include one code block per tab.
+
+````md
+::: code-group labels=[npm, pnpm, yarn]
+
+```bash
+npm i @dominikcz/greg
+```
+
+```bash
+pnpm add @dominikcz/greg
+```
+
+```bash
+yarn add @dominikcz/greg
+```
+
+:::
+````
+
+**Output:**
+
+::: code-group labels=[npm, pnpm, yarn]
+
+```bash
+npm i @dominikcz/greg
+```
+
+```bash
+pnpm add @dominikcz/greg
+```
+
+```bash
+yarn add @dominikcz/greg
+```
+
+:::
+
+### Component-tag syntax
+
+When writing `.svelte` pages/components directly, you can render tabs with
+the `CodeGroup` component.
+
+```svelte
+<script>
+  import CodeGroup from '$components/CodeGroup.svelte';
+
+  const tabs = ['npm', 'pnpm'];
+  const blocks = [
+    `<pre class="shiki"><code>npm i @dominikcz/greg</code></pre>`,
+    `<pre class="shiki"><code>pnpm add @dominikcz/greg</code></pre>`,
+  ];
+</script>
+
+<CodeGroup {tabs} {blocks} initialActive={0} />
+```
+
+**Output:**
+
+Equivalent tabbed UI as in the Markdown directive example above.
+
+## Labels inferred from code blocks
+
+When `labels=[...]` is omitted, labels are inferred from each block's language
+or code title.
+
+````md
+::: code-group
+
+```js [config.js]
+export default {
+  docsDir: 'docs',
+};
+```
+
+```ts [config.ts]
+export default {
+  docsDir: 'docs',
+} as const;
+```
+
+:::
+````
+
+**Output:**
+
+::: code-group
+
+```js [config.js]
+export default {
+  docsDir: 'docs',
+};
+```
+
+```ts [config.ts]
+export default {
+  docsDir: 'docs',
+} as const;
+```
+
+:::
+
+## Keyboard interaction
+
+- `Left` / `Right`: move between tabs
+- `Home` / `End`: jump to first/last tab
+- `Enter` or `Space`: activate focused tab

package/docs/reference/home-page.md

@@ -0,0 +1,232 @@
+---
+title: Home Page
+renderer: mdsvex
+---
+
+Greg does not use frontmatter-based layouts. Instead, the `<Hero>` and
+`<Features>` components are used directly inside Markdown pages to compose a
+landing / home page.
+
+For these components there is no dedicated directive/container shorthand
+(like `::: ...`). Use component tags directly (`<Hero ... />`,
+`<Features ... />`).
+
+## Authoring styles
+
+`Hero` and `Features` are available in both authoring contexts:
+
+- Markdown docs pages (`.md`) via component tags
+- Direct `.svelte` usage via imported components
+
+In Markdown pages, Greg auto-registers these components, so no import is needed.
+In plain `.svelte` files, you still need explicit imports.
+
+## Hero
+
+The `<Hero>` component renders a large introductory section with a name, tagline,
+optional image and call-to-action buttons.
+
+::: code-group labels=[markdown, output]
+
+<<< @/snippets/reference/home-hero-example.md
+
+<Hero
+  name="My Project"
+  text="The fastest way to document things."
+  tagline="Write once, ship everywhere."
+  image={{
+    light: { src: '/greg-logo-light.svg', alt: 'My Project logo' },
+    dark: { src: '/greg-logo-dark.svg', alt: 'My Project logo' },
+  }}
+  actions={[
+    { theme: 'brand', text: 'Get Started', link: '/guide/getting-started' },
+    { theme: 'alt', text: 'GitHub', link: 'https://github.com/dominikcz/greg' },
+  ]}
+/>
+
+:::
+
+### Direct component usage for Hero (`.svelte`)
+
+In `.svelte` files, import the component explicitly:
+
+::: code-group labels=[svelte, output]
+
+```svelte
+<script>
+  import Hero from '$components/Hero.svelte';
+</script>
+
+<Hero
+  name="My Project"
+  text="The fastest way to document things."
+  tagline="Write once, ship everywhere."
+  image={{
+    light: { src: '/greg-logo-light.svg', alt: 'My Project logo' },
+    dark: { src: '/greg-logo-dark.svg', alt: 'My Project logo' },
+  }}
+  actions={[
+    { theme: 'brand', text: 'Get Started', link: '/guide/getting-started' },
+    { theme: 'alt', text: 'GitHub', link: 'https://github.com/dominikcz/greg' },
+  ]}
+/>
+```
+
+<Hero
+  name="My Project"
+  text="The fastest way to document things."
+  tagline="Write once, ship everywhere."
+  image={{
+    light: { src: '/greg-logo-light.svg', alt: 'My Project logo' },
+    dark: { src: '/greg-logo-dark.svg', alt: 'My Project logo' },
+  }}
+  actions={[
+    { theme: 'brand', text: 'Get Started', link: '/guide/getting-started' },
+    { theme: 'alt', text: 'GitHub', link: 'https://github.com/dominikcz/greg' },
+  ]}
+/>
+
+:::
+
+### Props
+
+```ts
+interface HeroAction {
+  theme?: 'brand' | 'alt';   // default: 'brand'
+  text: string;
+  link: string;
+  target?: string;
+  rel?: string;
+}
+
+type ThemeImage =
+  | string // same image for both themes
+  | { src: string; alt?: string; width?: number | string; height?: number | string }
+  | {
+      light: string | { src: string; alt?: string; width?: number | string; height?: number | string };
+      dark: string | { src: string; alt?: string; width?: number | string; height?: number | string };
+      alt?: string;
+    };
+
+interface Props {
+  name?: string;       // product name - displayed with accent colour
+  text?: string;       // main tagline (h1)
+  tagline?: string;    // sub-tagline
+  image?: ThemeImage;  // optional hero image (right side)
+  actions?: HeroAction[];
+}
+```
+
+If you use a manual theme toggle, prefer the `light`/`dark` image pair form.
+A single image with only `@media (prefers-color-scheme)` follows system theme,
+not necessarily the in-app toggle state.
+
+### Snippet slots
+
+For advanced customisation, `Hero` exposes several Svelte snippet slots:
+
+| Snippet            | Position                             |
+| ------------------ | ------------------------------------ |
+| `heroBefore`       | Before the name/text block           |
+| `heroInfo`         | Replaces the entire name + tagline   |
+| `heroInfoAfter`    | After tagline, before action buttons |
+| `heroImage`        | Replaces the default image           |
+| `heroActionsAfter` | After the action buttons             |
+
+## Features
+
+The `<Features>` component renders a responsive grid of feature cards below the
+Hero section.
+
+::: code-group labels=[markdown, output]
+
+<<< @/snippets/reference/home-features-example.md
+
+<Features
+  features={[
+    { icon: 'docs', title: 'Markdown-first', details: 'Rich extensions, zero config.' },
+    { icon: 'vite', title: 'Vite-powered', details: 'Instant HMR and fast builds.' },
+    { icon: 'svelte', title: 'Svelte 5', details: 'Runes-based, no overhead.' },
+  ]}
+/>
+
+:::
+
+### Direct component usage (`.svelte`)
+
+In `.svelte` files, import the component explicitly:
+
+::: code-group labels=[svelte, output]
+
+```svelte
+<script>
+  import Features from '$components/Features.svelte';
+</script>
+
+<Features
+  features={[
+    { icon: 'docs', title: 'Markdown-first', details: 'Rich extensions, zero config.' },
+    { icon: 'vite', title: 'Vite-powered', details: 'Instant HMR and fast builds.' },
+    { icon: 'svelte', title: 'Svelte 5', details: 'Runes-based, no overhead.' },
+  ]}
+/>
+```
+
+<Features
+  features={[
+    { icon: 'docs', title: 'Markdown-first', details: 'Rich extensions, zero config.' },
+    { icon: 'vite', title: 'Vite-powered', details: 'Instant HMR and fast builds.' },
+    { icon: 'svelte', title: 'Svelte 5', details: 'Runes-based, no overhead.' },
+  ]}
+/>
+
+:::
+
+### Icon types
+
+Icons can be emoji strings, image URLs, or dark/light image pairs:
+
+```md
+<Features features={[
+  { icon: 'tool', title: 'Tooling', details: 'Fast setup.' },
+  { icon: { src: '/icons/rocket.svg' }, title: 'Launch', details: 'Ready to go.' },
+  { icon: { dark: '/icons/d.svg', light: '/icons/l.svg' }, title: 'Theme-aware', details: 'Matches color mode.' },
+]} />
+```
+
+### Feature props
+
+```ts
+interface Feature {
+  icon?: string | { src: string; alt?: string; width?: number; height?: number }
+              | { dark: string; light: string; alt?: string };
+  title: string;
+  details?: string;
+  link?: string;       // makes the whole card clickable
+  linkText?: string;   // "Learn more" style label
+  rel?: string;
+  target?: string;
+}
+```
+
+### Grid layout
+
+The grid automatically adapts based on the number of features:
+
+| Count         | Layout                 |
+| ------------- | ---------------------- |
+| 2             | 2-column               |
+| 3             | 3-column               |
+| 4 or 5        | 2 + 3 mixed            |
+| Multiple of 3 | 3-column               |
+| Other         | 4-column with wrapping |
+
+## Full home page example
+
+::: code-group labels=[markdown, output]
+
+<<< @/snippets/reference/home-full-example.md
+
+<!--@include: @/snippets/reference/home-full-example.md-->
+
+:::

package/docs/reference/index.md

@@ -0,0 +1,18 @@
+---
+title: Reference
+---
+
+# Reference
+
+API and component reference for Greg.
+
+- [`<MarkdownDocs>` Component](./markdowndocs) — props and Vite configuration
+- [Badge](./badge) — inline status badge component
+- [Carbon Ads](./carbon-ads) — advertising integration
+- [Code Group](./code-group) — tabbed code blocks
+- [Home Page — Hero & Features](./home-page) — landing page components
+- [Outline](./outline) — on-this-page panel
+- [Search](./search) — full-text search configuration
+- [Steps](./steps) — numbered procedural steps component
+- [Team Page](./team-page) — team member display components
+- [Theme & Styling](./theme) — CSS variables and dark/light mode