Improve docs structure and split advanced guides

Reorganize navigation around Quickstart, Guide, and Advanced sections and move advanced topics into focused pages. Update examples and option docs so snippets are valid, copy-pasteable, and aligned with current package behavior.

Author: TorstenDittmann

apps/documentation/docs/README.md

@@ -15,6 +15,7 @@ Bring the power of Markdoc right into your Svelte applications.
 
 ## Quick links
 
-- [Install](/guide/install/)
+- [Quickstart](/guide/install/)
 - [Configuration](/guide/configuration/)
+- [Advanced](/advanced/content-indexing/)
 - [GitHub](https://github.com/TorstenDittmann/svelte-markdoc-preprocess)

apps/documentation/docs/SUMMARY.md

@@ -1,11 +1,15 @@
 # Summary
 
 - [Introduction](README.md)
+- [Quickstart](guide/install.md)
 - Guide
-  - [Install](guide/install.md)
   - [Configuration](guide/configuration.md)
   - [Nodes](guide/nodes.md)
   - [Tags](guide/tags.md)
   - [Layouts](guide/layouts.md)
   - [Partials](guide/partials.md)
-  - [Advanced](guide/advanced.md)
+- Advanced
+  - [Indexing](advanced/content-indexing.md)
+  - [VS Code schema](advanced/vscode-schema.md)
+  - [Markdoc config](advanced/markdoc-config.md)
+  - [Code highlighting](advanced/highlighting.md)

apps/documentation/docs/_meta.json

@@ -0,0 +1,38 @@
+# Indexing
+
+Each `.markdoc` file exports `frontmatter`, so you can build content lists (for example blog indexes) from `load` functions.
+
+```md title="src/routes/blog/hello.markdoc"
+---
+title: My Blog Post
+description: This post explains how indexing works.
+date: 2026-01-01
+---
+
+# My Blog Post
+```
+
+```ts title="src/routes/blog/+page.server.ts"
+export function load() {
+    const modules = import.meta.glob('./*.markdoc', {
+        eager: true,
+    });
+
+    const posts = Object.entries(modules).map(([filepath, module]) => {
+        const { frontmatter } = module as {
+            frontmatter: {
+                title: string;
+                description?: string;
+                date?: string;
+            };
+        };
+
+        return {
+            slug: filepath.replace('./', '').replace('.markdoc', ''),
+            ...frontmatter,
+        };
+    });
+
+    return { posts };
+}
+```

apps/documentation/docs/advanced/content-indexing.md

@@ -0,0 +1,15 @@
+# Add custom code highlighting
+
+Use `highlighter` to transform fenced code blocks before rendering.
+
+```js title="svelte.config.js"
+import { markdoc } from 'svelte-markdoc-preprocess';
+
+markdoc({
+    highlighter: async (code, language) => {
+        return `<pre data-language="${language}"><code>${code}</code></pre>`;
+    },
+});
+```
+
+The function receives `(code, language)` and must return an HTML string.

apps/documentation/docs/advanced/highlighting.md

@@ -0,0 +1,25 @@
+# Pass custom Markdoc config
+
+Use the `config` option to pass options directly to Markdoc.
+
+```js title="svelte.config.js"
+import { markdoc } from 'svelte-markdoc-preprocess';
+
+markdoc({
+    config: {
+        variables: {
+            company: 'Acme',
+        },
+        functions: {
+            includes: {
+                transform(parameters) {
+                    const [array, value] = Object.values(parameters);
+                    return Array.isArray(array) ? array.includes(value) : false;
+                },
+            },
+        },
+    },
+});
+```
+
+Refer to the Markdoc config reference for all available options: https://markdoc.dev/docs/config#options

apps/documentation/docs/advanced/markdoc-config.md

@@ -0,0 +1,20 @@
+# Visual Studio Code schema support
+
+With `generateSchema: true` (default), the preprocessor writes `.svelte-kit/markdoc_schema.js`.
+
+You can point the official [Markdoc VS Code extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support) to that file in `markdoc.config.json`:
+
+```json title="markdoc.config.json"
+[
+    {
+        "id": "my-site",
+        "path": "src/routes",
+        "schema": {
+            "path": ".svelte-kit/markdoc_schema.js",
+            "type": "esm",
+            "property": "default",
+            "watch": true
+        }
+    }
+]
+```

apps/documentation/docs/advanced/vscode-schema.md

@@ -1,82 +1,117 @@
 # Configuration
 
-You can pass the configuration to the preprocessor in the `svelte.config.js` like this:
+Pass options to `markdoc(...)` inside your `svelte.config.js`.
 
 ```js title="svelte.config.js"
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
 import { markdoc } from 'svelte-markdoc-preprocess';
 
+/** @type {import('@sveltejs/kit').Config} */
 const config = {
     preprocess: [
         vitePreprocess(),
         markdoc({
-            // configuration here
+            // options here
         }),
     ],
+    extensions: ['.markdoc', '.svelte'],
 };
+
+export default config;
 ```
 
 ## Options
 
-#### `extensions`
+### `extensions`
+
+**Type:** `string[]`
+
+**Default:** `['.markdoc', '.mdoc', '.markdown', '.md']`
+
+File extensions to process with Markdoc.
+
+### `nodes`
+
+**Type:** `string | null`
+
+**Default:** `null`
+
+Absolute path to a `.svelte` file that exports node components from `<script module>`.
 
-**Type**: `string[]`
+### `tags`
 
-**Default**: `['.markdoc', '.mdoc', '.markdown', '.md']`
+**Type:** `string | null`
 
-Extensions to be processed.
+**Default:** `null`
 
-#### `nodes`
+Absolute path to a `.svelte` file that exports tag components from `<script module>`.
 
-**Type**: `string | null`
+### `partials`
 
-**Default**: `null`
+**Type:** `string | null`
 
-Absoulute path to the `.svelte` file exporting components for nodes.
+**Default:** `null`
 
-#### tags
+Absolute path to the partials directory.
 
-**Type**: `string | null`
+### `generateSchema`
 
-**Default**: `null`
+**Type:** `boolean`
 
-Absoulute path to the `.svelte` file exporting components for tags.
+**Default:** `true`
 
-#### partials
+Generates `.svelte-kit/markdoc_schema.js` for the official [Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support).
 
-**Type**: `string`
+### `layouts`
 
-**Default**: `null`
+**Type:** `Record<string, string> | null`
 
-Absoulute path to the folder for partials.
+**Default:** `null`
 
-#### generateSchema
+Map of layout names to absolute `.svelte` file paths.
 
-**Type**: `boolean`
+### `validationThreshold`
 
-**Default**: `true`
+**Type:** `"debug" | "info" | "warning" | "error" | "critical" | null`
 
-Generate schema files under `./svelte-kit/markdoc-schema.json` to be used with the official [Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support).
+**Default:** `'error'`
 
-#### layouts
+Minimum validation level that should fail the build.
 
-**Type**: `Record<string, string> | null`
+### `allowComments`
 
-**Default**: `null`
+**Type:** `boolean`
 
-Layouts to be used for pages.
+**Default:** `false`
 
-#### validationThreshold
+Allow HTML comments (`<!-- -->`) in Markdoc files.
 
-**Type**: `"error" | "debug" | "info" | "warning" | "critical"`
+### `config`
 
-**Default**: `error`
+**Type:** `ConfigType | null`
 
-The threshold for validation errors to stop the build.
+**Default:** `null`
 
-#### allowComments
+Pass configuration directly to Markdoc (for example `variables`, `functions`, `validation`, `tags`, `nodes`, and `partials`).
 
-**Type**: `boolean`
+### `highlighter`
 
-**Default**: `false`
+**Type:** `((code: string, language: string) => Promise<string>) | null`
 
-Allow comments in the markdown files.
+**Default:** `null`
+
+Custom syntax highlighter used for fenced code blocks. The returned string is rendered as HTML.
+
+```js title="svelte.config.js"
+import { markdoc } from 'svelte-markdoc-preprocess';
+
+markdoc({
+    highlighter: async (code, language) => {
+        if (language === 'js') {
+            return `<span class="language-js">${code}</span>`;
+        }
+
+        return code;
+    },
+});
+```