From f1e4f0a1aeed94dd244b475177a811a58819a6c6 Mon Sep 17 00:00:00 2001
From: Johann Schopplich <mail@johannschopplich.com>
Date: Thu, 8 Aug 2024 08:57:37 +0200
Subject: [PATCH] docs: add Kirby Headless docs

---
 components/Header.vue                         |  20 +-
 content/1.docs/1.live-preview/1.index.md      |  16 +-
 content/1.docs/1.live-preview/_dir.yml        |   1 +
 .../1.docs/2.content-translator/1.index.md    |  18 +-
 content/1.docs/2.content-translator/_dir.yml  |   1 +
 content/1.docs/3.headless/1.index.md          |  50 +++++
 content/1.docs/3.headless/2.usage.md          | 191 +++++++++++++++++
 content/1.docs/3.headless/3.field-methods.md  | 194 ++++++++++++++++++
 content/1.docs/3.headless/4.page-methods.md   |  44 ++++
 content/1.docs/3.headless/5.api-builder.md    | 120 +++++++++++
 content/1.docs/3.headless/6.migration.md      |  22 ++
 content/1.docs/3.headless/_dir.yml            |   2 +
 pages/docs.vue                                |   4 +-
 13 files changed, 652 insertions(+), 31 deletions(-)
 create mode 100644 content/1.docs/3.headless/1.index.md
 create mode 100644 content/1.docs/3.headless/2.usage.md
 create mode 100644 content/1.docs/3.headless/3.field-methods.md
 create mode 100644 content/1.docs/3.headless/4.page-methods.md
 create mode 100644 content/1.docs/3.headless/5.api-builder.md
 create mode 100644 content/1.docs/3.headless/6.migration.md
 create mode 100644 content/1.docs/3.headless/_dir.yml

diff --git a/components/Header.vue b/components/Header.vue
index 71dc2d9..7aa6140 100644
--- a/components/Header.vue
+++ b/components/Header.vue
@@ -17,23 +17,27 @@ const links = computed<HeaderLink[]>(() => [
       {
         label: "Live Preview",
         to: "/live-preview",
+        icon: "i-ri-presentation-fill",
         description: "Real-time page preview",
       },
       {
         label: "Content Translator",
         to: "/content-translator",
-        description: "DeepL-powered translations",
+        icon: "i-ri-translate",
+        description: "Content translation in the Panel or server-side",
       },
       {
         label: "Kirby Copilot",
         to: "https://kirbycopilot.com",
+        icon: "i-ri-sparkling-fill",
         description: "AI-powered content generation",
         target: "_blank",
       },
       {
         label: "Kirby SEO Audit",
-        description: "State-of-the-art SEO analysis",
         to: "https://kirbyseo.com",
+        icon: "i-ri-seo-fill",
+        description: "State-of-the-art SEO analysis",
         target: "_blank",
       },
     ],
@@ -44,17 +48,17 @@ const links = computed<HeaderLink[]>(() => [
       {
         label: "Live Preview",
         to: "/docs/live-preview",
-        description: "Content changes live in the Panel",
+        icon: "i-ri-presentation-fill",
       },
       {
         label: "Content Translator",
         to: "/docs/content-translator",
-        description: "Translate your content in the Panel or with the PHP API",
+        icon: "i-ri-translate",
       },
       {
-        label: "Kirby Headless",
+        label: "Headless",
         to: "/docs/headless",
-        description: "Kirby, but headless only",
+        icon: "i-ri-braces-fill",
       },
     ],
   },
@@ -70,8 +74,6 @@ const links = computed<HeaderLink[]>(() => [
 ]);
 
 const navigation = inject<Ref<NavItem[]>>("navigation", ref([]));
-// TODO: Remove when fixed upstream
-const _mapContentNavigation = mapContentNavigation;
 </script>
 
 <template>
@@ -115,7 +117,7 @@ const _mapContentNavigation = mapContentNavigation;
 
     <template #panel>
       <UNavigationTree
-        :links="_mapContentNavigation(navigation)"
+        :links="mapContentNavigation(navigation)"
         :multiple="false"
         default-open
       />
diff --git a/content/1.docs/1.live-preview/1.index.md b/content/1.docs/1.live-preview/1.index.md
index 82c34d8..ba1b07b 100644
--- a/content/1.docs/1.live-preview/1.index.md
+++ b/content/1.docs/1.live-preview/1.index.md
@@ -1,15 +1,13 @@
 ---
-title: Installation
+title: Getting Started
 description: Learn how to install and configure Kirby Live Preview in your Kirby project.
 ---
 
-## Quick Start
-
-### Step 1: Install the Plugin
+## Step 1: Install the Plugin
 
 Although it is a commercial plugin, you can download and test the plugin in your local environment before purchasing it.
 
-#### Composer
+### Composer
 
 The recommended way to install the plugin is via Composer. To install the plugin, run the following command in your terminal:
 
@@ -29,7 +27,7 @@ You can now delete the `auth.json` file from the root directory.
 
 ::
 
-#### Download
+### Download
 
 Head over to the [releases page](https://github.com/kirby-tools/kirby-live-preview/releases) and download the latest version of the plugin as a ZIP file. Extract the contents of this ZIP file to your `site/plugins` folder. It should look like this:
 
@@ -39,7 +37,7 @@ site/plugins/
 │  └─ … All plugin files
 ```
 
-### Step 2: Blueprint Setup
+## Step 2: Blueprint Setup
 
 Select a site or page blueprint to which you want to add the Live Preview section. Add the following section configuration to the blueprint file:
 
@@ -49,7 +47,7 @@ sections:
     type: preview
 ```
 
-### Step 3: Customize the Live Preview
+## Step 3: Customize the Live Preview
 
 Fit the Live Preview section to your blueprint layout and customize it to your needs: It can be part of any column and can even be sticky. The latter is useful for previewing content changes side-by-side with blocks or other fields:
 
@@ -76,7 +74,7 @@ Try navigating through the preview – if you click on a site link, such as in t
 
 For mor configuration options, see the [Configuration](/docs/live-preview/configuration) guide.
 
-### Step 4: Buy a License
+## Step 4: Buy a License
 
 You can test the plugin locally. However, you need to purchase a license to use the plugin in production environments.
 
diff --git a/content/1.docs/1.live-preview/_dir.yml b/content/1.docs/1.live-preview/_dir.yml
index ffcbc67..99e4a7b 100644
--- a/content/1.docs/1.live-preview/_dir.yml
+++ b/content/1.docs/1.live-preview/_dir.yml
@@ -1 +1,2 @@
 title: Live Preview
+icon: i-ri-presentation-fill
diff --git a/content/1.docs/2.content-translator/1.index.md b/content/1.docs/2.content-translator/1.index.md
index 67947fc..e5ea295 100644
--- a/content/1.docs/2.content-translator/1.index.md
+++ b/content/1.docs/2.content-translator/1.index.md
@@ -1,15 +1,13 @@
 ---
-title: Installation
+title: Getting Started
 description: Learn how to install and configure the plugin in your Kirby project.
 ---
 
-## Quick Start
-
-### Step 1: Install the Plugin
+## Step 1: Install the Plugin
 
 Although it is a commercial plugin, you can download and test the plugin in your local environment before purchasing it.
 
-#### Composer
+### Composer
 
 The recommended way to install the plugin is via Composer. To install the plugin, run the following command in your terminal:
 
@@ -17,7 +15,7 @@ The recommended way to install the plugin is via Composer. To install the plugin
 composer require johannschopplich/kirby-content-translator
 ```
 
-#### Download
+### Download
 
 Head over to the [releases page](https://github.com/kirby-tools/kirby-content-translator/releases) and download the latest version of the plugin as a ZIP file. Extract the contents of this ZIP file to your `site/plugins` folder. It should look like this:
 
@@ -27,7 +25,7 @@ site/plugins/
 │  └─ … All plugin files
 ```
 
-### Step 2: Configure DeepL
+## Step 2: Configure DeepL
 
 By default, this plugin uses the [DeepL API](https://www.deepl.com) to translate your content. However, you can also use any other translation service by defining a [custom translator function](/docs/content-translator/configuration#custom-translator-function).
 
@@ -46,7 +44,7 @@ return [
 ];
 ```
 
-### Step 3: Blueprint Setup
+## Step 3: Blueprint Setup
 
 Open a site, site, or page blueprint file where you want to add the Content Translator. Add the following section configuration to the blueprint file:
 
@@ -61,7 +59,7 @@ This will add a new section to the Panel where you can import and translate cont
 ::preview{src="/img/kirby-content-translator-section-activate.png"}
 ::
 
-### Step 4: Translate Your Content
+## Step 4: Translate Your Content
 
 Open the Panel and navigate to the page where you added the Content Translator section. Select one of the secondary languages from the Kirby's language drop-down list. You will see two new buttons in the section: **Import** and **Translate**.
 
@@ -75,7 +73,7 @@ By default, all text-like fields are translated. You can fully customize the con
 
 For more configuration options, see the [Configuration](/docs/live-preview/configuration) guide.
 
-### Step 5: Buy a License
+## Step 5: Buy a License
 
 You can test the plugin locally. However, you need to purchase a license to use the plugin in production environments.
 
diff --git a/content/1.docs/2.content-translator/_dir.yml b/content/1.docs/2.content-translator/_dir.yml
index e0e60e4..1917e74 100644
--- a/content/1.docs/2.content-translator/_dir.yml
+++ b/content/1.docs/2.content-translator/_dir.yml
@@ -1 +1,2 @@
 title: Content Translator
+icon: i-ri-translate
diff --git a/content/1.docs/3.headless/1.index.md b/content/1.docs/3.headless/1.index.md
new file mode 100644
index 0000000..b1343b2
--- /dev/null
+++ b/content/1.docs/3.headless/1.index.md
@@ -0,0 +1,50 @@
+---
+title: Getting Started
+description: The Kirby Headless plugin enhances your Kirby site with headless capabilities.
+---
+
+## Introduction
+
+This plugin is designed for developers who want to use Kirby's backend to serve content to a frontend application, static site generator, or mobile application. You can either add headless functionality to your existing Kirby site, or use this plugin to build a headless-first CMS from scratch.
+
+::callout{icon="i-ri-information-line"}
+Check out to the [Kirby Headless Starter](https://github.com/johannschopplich/kirby-headless-starter) repository for a ready-to-use headless-only setup!
+::
+
+## Key Features
+
+- 🧩 Optional bearer token authentication for [KQL](/docs/headless/usage#kirby-query-language-kql) and custom API endpoints
+- 🧱 Resolve fields in blocks: [UUIDs to file and page objects](/docs/headless/field-methods) or [any other field](/docs/headless/field-methods)
+- ⚡️ Cached KQL queries
+- 🌐 Multi-language support for KQL queries
+- 😵 Built-in CORS handling
+- 🍢 Express-esque [API builder](/docs/headless/api-builder) with middleware support
+- 🗂 Return [JSON from templates](/docs/headless/usage#json-templates) instead of HTML
+
+## Installation
+
+### Composer
+
+The recommended way to install the plugin is via Composer. To install the plugin, run the following command in your terminal:
+
+```bash
+composer require johannschopplich/kirby-content-translator
+```
+
+### Download
+
+Head over to the [releases page](https://github.com/johannschopplich/kirby-headless/releases) and download the latest version of the plugin as a ZIP file. Extract the contents of this ZIP file to your `site/plugins` folder. It should look like this:
+
+```
+site/plugins/
+├─ kirby-headless/
+│  └─ … Plugin files
+```
+
+## Setup
+
+Nothing to do here! The plugin is ready to use out of the box. If you want to customize the plugin, you can do so by [configuring it](/docs/headless/usage).
+
+::callout{icon="i-ri-information-line"}
+By default, Kirby Headless doesn't interfere with Kirby's default routing. Thus, it won't affect your existing routes or templates.
+::
diff --git a/content/1.docs/3.headless/2.usage.md b/content/1.docs/3.headless/2.usage.md
new file mode 100644
index 0000000..ff05d2e
--- /dev/null
+++ b/content/1.docs/3.headless/2.usage.md
@@ -0,0 +1,191 @@
+---
+title: Usage
+description: Configure the Kirby Headless plugin to your needs.
+---
+
+## Authentication
+
+The Kirby Headless plugin exposes your content to the public by default. To secure your API, you can enable bearer token authentication for the KQL and custom API endpoints. This is especially useful for [KQL](https://github.com/getkirby/kql) requests, as Kirby's default KQL endpoint only supports basic authentication.
+
+To enable bearer token authentication, set the `headless.token` global option in your `config.php` to a secret string:
+
+```php [config.php]
+return [
+    'headless' => [
+        'token' => 'test'
+    ]
+];
+```
+
+You will then need to include the HTTP header `Authentication: Bearer {token}` with every request.
+
+::callout{icon="i-ri-information-line"}
+The internal `/api/kql` endpoint will always enforce bearer authentication, unless you explicitly disable it by setting the `kql.auth` option to `false`.
+::
+
+## Cross Origin Resource Sharing (CORS)
+
+CORS issues are a common problem when fetching data from a different domain. To allow cross-origin requests, Kirby Headless responds with the appropriate CORS headers for preflight requests. You can customize the CORS configuration in your `config.php`:
+
+```php [config.php]
+return [
+    'headless' => [
+        // Default CORS configuration
+        'cors' => [
+            'allowOrigin' => '*',
+            'allowMethods' => 'GET, POST, OPTIONS',
+            'allowHeaders' => 'Accept, Content-Type, Authorization, X-Language',
+            'maxAge' => '86400',
+        ]
+    ]
+];
+```
+
+## Kirby Query Language (KQL)
+
+It is common to authenticate API requests with a token, which is not possible with the default KQL endpoint (`/api/query` as defined by the official [KQL plugin](https://github.com/getkirby/kql)). To solve this problem, this plugin adds a new KQL endpoint under `/api/kql` that supports the following features:
+
+- Bearer token authentication
+- Query response caching
+- Multi-language support
+
+To enable the bearer token authentication for KQL query requests to `/api/kql`, set the following option in your `config.php`:
+
+```php [config.php]
+return [
+    // Default to token-based authentication
+    'kql' => [
+        'auth' => 'bearer'
+    ]
+];
+```
+
+Now fetch the KQL query results as you normally would, but include an `Authentication' header with the bearer token in your request:
+
+```ts
+const response = await fetch("https://example.com/api/kql", {
+  method: "POST",
+  body: {
+    query: "site",
+    select: {
+      title: true,
+      photography: {
+        query: "page('photography').children",
+        select: ["title", "url"],
+      },
+    },
+  },
+  headers: {
+    Authentication: `Bearer ${process.env.KIRBY_API_TOKEN}`,
+  },
+});
+
+const data = await response.json();
+console.log(data);
+```
+
+### Basic Authentication for KQL
+
+If you prefer the default **basic authentication** method, you can still enable it by setting the `kql.auth` option to `true`. This will **disable bearer token authentication**, but still provide features like caching and multi-language support:
+
+```php [config.php]
+return [
+    // Enable basic authentication for the Kirby API (required for KQL)
+    'api' => [
+        'basicAuth' => true
+    ],
+
+    // Default to basic authentication
+    'kql' => [
+        'auth' => true
+    ]
+];
+```
+
+::callout{icon="i-ri-information-line"}
+The default KQL endpoint `/api/query` always continues to use basic authentication and also derives the `kql.auth` configuration option.
+::
+
+## Panel Configuration
+
+### Preview URL to the Frontend
+
+If you're running a headless CMS, the default preview links from the Kirby Panel won't make much sense because they point to the backend URL. We need to change the hostname of the generated preview URLs to the frontend URL. To do this, set the `preview` option in your template to a Kirby query that calls the `frontendUrl` page method provided by this plugin:
+
+```yaml [site/blueprints/pages/default.yml]
+options:
+  # Or `site.frontendUrl` for the `site.yml`
+  preview: "{{ page.frontendUrl }}"
+```
+
+Finally, set the `frontendUrl` option in your `config.php`:
+
+```php [config.php]
+return [
+    'headless' => [
+        'panel' => [
+            'frontendUrl' => 'https://example.com'
+        ]
+    ]
+];
+```
+
+If the value is empty, the preview button will be disabled altogether.
+
+### Redirect to the Panel
+
+If your Kirby project is headless only and no visual content is served, you may want to redirect editors to the Panel when they visit the backend. You could create a default template with a redirect, but it's easier to set the `redirect` option in your `config.php`:
+
+```php [config.php]
+return [
+    'headless' => [
+        'panel' => [
+            'redirect' => true
+        ]
+    ]
+];
+```
+
+## JSON Templates
+
+When writing a Kirby template, it will be rendered as HTML by default. To opt-in to JSON templates, you can encode the template data as JSON and return it as a response. This is useful for headless setups where KQL is not sufficient or you want to control the data structure in PHP.
+
+Kirby Headless doesn't interfere with Kirby's default routing. To overwrite Kirby's global routing to return JSON templates, set the `globalRoutes` option in your `config.php`:
+
+```php [config.php]
+return [
+    'headless' => [
+        'globalRoutes' => true
+    ]
+];
+```
+
+### Template Example
+
+Writing templates as JSON is straightforward. Here is an example of how to encode the data of an `about` template as JSON:
+
+```php [site/templates/about.php]
+$data = [
+  'title' => $page->title()->value(),
+  'layout' => $page->layout()->toLayouts()->toArray(),
+  'address' => $page->address()->value(),
+  'email' => $page->email()->value(),
+  'phone' => $page->phone()->value(),
+  'social' => $page->social()->toStructure()->toArray()
+];
+
+echo \Kirby\Data\Json::encode($data);
+```
+
+To fetch the JSON template data, you can use the following JavaScript example:
+
+```ts
+const response = await fetch("https://example.com/about", {
+  headers: {
+    Authentication: `Bearer ${process.env.KIRBY_API_TOKEN}`,
+  },
+});
+
+const data = await response.json();
+console.log(data);
+```
diff --git a/content/1.docs/3.headless/3.field-methods.md b/content/1.docs/3.headless/3.field-methods.md
new file mode 100644
index 0000000..1ef5769
--- /dev/null
+++ b/content/1.docs/3.headless/3.field-methods.md
@@ -0,0 +1,194 @@
+---
+title: Field Methods
+description: Kirby Headless offers field methods to resolve data in blocks and layouts.
+---
+
+## `toResolvedBlocks()`
+
+The `toResolvedBlocks()` method is a wrapper around Kirby's [`toBlocks()`](https://getkirby.com/docs/reference/templates/field-methods/to-blocks) method. It resolves fields in blocks to the desired output by running them through resolver functions.
+
+For example, the `toBlocks()` method returns UUIDs for the `files` and `pages` fields. To leave these UUIDs as they are would require you to resolve them in your frontend application. Instead, you can use the `toResolvedBlocks()` method to resolve these UUIDs into file and page objects on the server. This way, you can access the properties of these objects directly in your frontend.
+
+When using `toBlocks()`, a single block as part of the blocks JSON response might look like this:
+
+```json
+{
+  "content": {
+    "image": ["file://BYXR0pvumEbfTknP"],
+    "alt": "Staring at stars"
+  },
+  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
+  "isHidden": false,
+  "type": "image"
+}
+```
+
+Instead, when using `toResolvedBlocks()`, the same block would look as follows. Note that the `image` field is now resolved to a file object:
+
+```json
+{
+  "content": {
+    "alt": "Staring at stars",
+    "image": {
+      "url": "http://cacao-kit-backend.test/media/pages/notes/exploring-the-universe/a6c422e141-1714659501/tent-in-the-woods.jpg",
+      "width": 1024,
+      "height": 683
+    }
+  },
+  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
+  "isHidden": false,
+  "type": "image"
+}
+```
+
+You can define which fields of which blocks need resolving in your `config.php`. To simplify `files` and `pages` resolving, Kirby Headless comes with default resolvers for these fields. You can also define custom resolvers for specific fields in specific blocks.
+
+For a production-ready boilerplate, you can use the 🍫 [Cacao Kit frontend](https://github.com/johannschopplich/cacao-kit-frontend) which uses this field method.
+
+### Files and Pages Resolver
+
+In most cases, you want to resolve the `files` and `pages` fields in your blocks. To do so, you can define which fields of which blocks should be resolved in your `config.php`:
+
+```php [config.php]
+return [
+    'blocksResolver' => [
+        // Define which fields of which blocks should be resolved
+        'files' => [
+            // Resolve the `image` field in the `intro` block as a file
+            'intro' => ['image']
+        ],
+        'pages' => [
+            // Resolve the `link` field in the `note` block as a page
+            'note' => ['link']
+        ]
+    ]
+];
+```
+
+Now, all `files` and `pages` fields in the `intro` and `note` blocks will be resolved to file and page objects, respectively.
+
+You can customize the resolver output by defining a custom resolver (overriding the default resolvers) for the `files` and `pages` fields in your `config.php`. Both resolver options accept a closure that takes the `File` or `Page` model as its argument and returns an array of properties, just like the default resolver.
+
+For reference, the default values for the `files` and `pages` resolvers are:
+
+```php [config.php]
+return [
+    'blocksResolver' => [
+        'defaultResolvers' => [
+            'files' => fn (\Kirby\Cms\File $image) => [
+              'url' => $image->url(),
+              'width' => $image->width(),
+              'height' => $image->height(),
+              'srcset' => $image->srcset(),
+              'alt' => $image->alt()->value()
+            ],
+            'pages' => fn (\Kirby\Cms\Page $page) => [
+                'uri' => $page->uri(),
+                'title' => $page->title()->value()
+            ]
+        ]
+    ]
+];
+```
+
+### Custom Resolvers
+
+Default resolvers are probably not enough for your use case. If you need a custom resolver for links, structures, or any other field in a particular block, you can use the `blocksResolver.resolvers` option. It takes an array of resolvers, where the key is `{blockName}:{fieldName}` and the value is a closure that takes the field and block as its arguments and returns an array of properties.
+
+You have complete control over the output of the resolved fields. For example, you can resolve the `link` field of the `intro` block to a custom output:
+
+```php [config.php]
+return [
+    'blocksResolver' => [
+        'resolvers' => [
+            // Resolve the field `link` of the block `intro` to a custom output
+            'intro:link' => fn (\Kirby\Content\Field $field, \Kirby\Cms\Block $block) => [
+                'value' => $field->value(),
+                'uri' => $field->toPage()?->uri()
+            ]
+            // Resolve the KirbyText of the field `text` of the `note` block
+            'note:text' => function (\Kirby\Content\Field $field, \Kirby\Cms\Block $block) {
+                return $field->kirbytext()->value()
+            }
+        ]
+    ]
+];
+```
+
+### Replace Field Values
+
+By default, resolved fields will replace the source field values in the given block. If you want to keep the source field values and store the resolved content in a separate key, you can set the `resolvedKey` option to a custom key:
+
+```php [config.php]
+return [
+    'blocksResolver' => [
+        'resolvedKey' => 'resolved'
+    ]
+];
+```
+
+With this configuration, all resolved fields will be stored in a key named `resolved`, leaving the original field values untouched. A resolved block might look like this:
+
+```json
+{
+  "content": {
+    "alt": "Staring at stars",
+    "image": ["file://BYXR0pvumEbfTknP"],
+    "resolved": {
+      "image": {
+        "url": "http://cacao-kit-backend.test/media/pages/notes/exploring-the-universe/a6c422e141-1714659501/tent-in-the-woods.jpg",
+        "width": 1024,
+        "height": 683
+      }
+    }
+  },
+  "id": "a1c0f653-2e36-4b07-a7fa-d22ef27dd114",
+  "isHidden": false,
+  "type": "image"
+}
+```
+
+## `resolvePermalinks()`
+
+::callout{icon="i-ri-information-line"}
+Acts the same as Kirby's built-in `permalinksToUrls()` method, but supports a custom URL parser.
+::
+
+This field method resolves page and file permalinks to their respective URLs. It is primarily intended for usage with KQL queries, since the value of `writer` fields contains permalink URLs such as `/@/page/nDvVIAwDBph4uOpm`. But the method works with any field values that contains permalinks in `href` or `src` attributes.
+
+For headless usage, you may want to remove the origin from the URL and just return the path. You can do this by defining a custom URL parser in your `config.php`:
+
+```php [config.php]
+return [
+    'permalinksResolver' => [
+        // Strip the origin from the URL
+        'urlParser' => function (string $url, \Kirby\Cms\App $kirby) {
+            $path = parse_url($url, PHP_URL_PATH);
+            return $path;
+        }
+    ]
+];
+```
+
+Or in multi-language setups, you may want to remove a language prefix like `/de` from the URL:
+
+```php [config.php]
+return [
+    'permalinksResolver' => [
+        // Strip the language code prefix from German URLs
+        'urlParser' => function (string $url, \Kirby\Cms\App $kirby) {
+            $path = parse_url($url, PHP_URL_PATH);
+
+            if (str_starts_with($path, '/de')) {
+                return substr($path, 3);
+            }
+
+            return $path;
+        }
+    ]
+];
+```
+
+## `toResolvedLayouts()`
+
+The `toResolvedLayouts()` method is a wrapper around Kirby's [`toLayouts()`](https://getkirby.com/docs/reference/templates/field-methods/to-layouts) method. Under the hood, it uses the `toResolvedBlocks()` method to resolve fields in blocks. You can use the same `files`, `pages`, and custom resolvers as with the `toResolvedBlocks()` method.
diff --git a/content/1.docs/3.headless/4.page-methods.md b/content/1.docs/3.headless/4.page-methods.md
new file mode 100644
index 0000000..7736933
--- /dev/null
+++ b/content/1.docs/3.headless/4.page-methods.md
@@ -0,0 +1,44 @@
+---
+title: Page Methods
+description: Page methods for headless sites.
+---
+
+## `i18nMeta()`
+
+The `i18nMeta()` method returns an array including the title and URI for the current page in all available languages. This is useful for the frontend application to build a language switcher.
+
+Given a KQL query like this:
+
+```ts
+import type { KirbyQuerySchema } from "kirby-types";
+
+export const pageQuery: KirbyQuerySchema = {
+  query: 'page("home")',
+  select: {
+    title: true,
+    i18nMeta: true,
+  },
+};
+```
+
+The JSON response from the KQL API might look like this:
+
+```json
+{
+  "code": 200,
+  "status": "OK",
+  "result": {
+    "title": "Home",
+    "i18nMeta": {
+      "en": {
+        "title": "Home",
+        "uri": "home"
+      },
+      "de": {
+        "title": "Startseite",
+        "uri": "home"
+      }
+    }
+  }
+}
+```
diff --git a/content/1.docs/3.headless/5.api-builder.md b/content/1.docs/3.headless/5.api-builder.md
new file mode 100644
index 0000000..ce5132e
--- /dev/null
+++ b/content/1.docs/3.headless/5.api-builder.md
@@ -0,0 +1,120 @@
+---
+title: API Builder
+description: Use the built-in API builder to create complex API routes with ease.
+---
+
+This headless starter includes an Express-esque API builder, defined in the [`JohannSchopplich\Headless\Api\Api` class](https://github.com/johannschopplich/kirby-headless/blob/main/src/classes/Api/Api.php). You can use it to reuse logic such as handling a token or validating some other incoming data.
+
+Take a look at the [built-in routes](https://github.com/johannschopplich/kirby-headless/src/extensions/routes.php) to get an idea of how you can use the API builder to chain complex route logic.
+
+## Examples
+
+### Extend Kirby's Routing
+
+The following example demonstrates how to create a simple API route that returns a JSON response. It is accessible under `/hello-world`.
+
+```php [config.php]
+use JohannSchopplich\Headless\Api\Api;
+use JohannSchopplich\Headless\Api\Middlewares;
+
+return [
+    'routes' => [
+        [
+            'pattern' => 'hello-world',
+            'method' => 'GET',
+            'action' => Api::createHandler(
+                // Middleware to check if a bearer token is sent with the request
+                [Middlewares::class, 'hasBearerToken'],
+                // Handler function to execute if the middleware passes
+                function (array $context) {
+                    // Access the `foo` query parameter
+                    $foo = kirby()->request()->get('foo');
+
+                    // Do something with `$foo` here
+
+                    return Api::createResponse(200, [
+                        'foo' => $foo
+                    ]);
+                }
+            )
+        ]
+    ]
+];
+```
+
+### Extend Kirby's API
+
+If you want to create an API route that is accessible under `/api/my-endpoint`, you can use the `api` option in your `config.php`. This will add the endpoint to [Kirby's API routes](https://getkirby.com/docs/reference/plugins/extensions/api).
+
+```php [config.php]
+use JohannSchopplich\Headless\Api\Api;
+use JohannSchopplich\Headless\Api\Middlewares;
+
+return [
+    'api' => [
+        'routes' => [
+            [
+                'pattern' => 'my-endpoint',
+                // Accept only POST requests
+                'method' => 'POST',
+                // Disable authentication, since the middleware will check for a bearer token
+                'auth' => false,
+                'action' => Api::createHandler(
+                    // Middleware to check if a bearer token is sent with the request
+                    [Middlewares::class, 'hasBearerToken'],
+                    // Handler function to execute if the middleware passes
+                    function (array $context) {
+                        $foo = kirby()->request()->get('foo');
+
+                        // Do something with `$foo` here
+
+                        return Api::createResponse(201, [
+                            'foo' => $foo
+                        ]);
+                    }
+                )
+            ]
+        ]
+    ]
+];
+```
+
+## Middlewares
+
+You can use one of the [built-in middlewares](https://github.com/johannschopplich/kirby-headless/blob/main/src/classes/Middlewares.php) or define your own custom middleware.
+
+This example demonstrates how to create a custom middleware that checks if a `date` query parameter is sent with the request. If not, it will return a 401 error:
+
+```php
+use JohannSchopplich\Headless\Api\Api;
+
+$hasDateQuery = function (array $context) {
+    if (empty(kirby()->request()->get('date'))) {
+        return Api::createResponse(401);
+    }
+};
+```
+
+Use the middleware in your route configuration like this:
+
+```php
+use JohannSchopplich\Headless\Api\Api;
+
+return [
+    'routes' => [
+        [
+            'pattern' => 'my-endpoint',
+            'method' => 'POST',
+            'action' => Api::createHandler(
+                $hasDateQuery,
+                function (array $context) {
+                    $date = kirby()->request()->get('date');
+                    return Api::createResponse(201, [
+                        'date' => $date
+                    ]);
+                }
+            )
+        ]
+    ]
+];
+```
diff --git a/content/1.docs/3.headless/6.migration.md b/content/1.docs/3.headless/6.migration.md
new file mode 100644
index 0000000..5f62e86
--- /dev/null
+++ b/content/1.docs/3.headless/6.migration.md
@@ -0,0 +1,22 @@
+---
+title: Migration
+description: Follow this guide to migrate between Kirby Headless versions.
+---
+
+## Migrating from v3 to v4
+
+Kirby Headless v4 contains a breaking change: the result of the `toResolvedBlocks()` field method has changed. Before, the resolved blocks fields were nested within the `resolved` key. Now the resolved fields overwrite the original fields. This results in less duplication and a cleaner structure.
+
+Update your frontend code to reflect this change. For example, instead of accessing the `resolved` key like `block.content.resolved?.team`, you can now access the resolved field directly like `block.content.team`.
+
+### Resolved Key
+
+If you don't want to update your frontend code, you can still update to v4 and use the old structure by defining a `resolvedKey` in your `config.php`:
+
+```php [config.php]
+return [
+    'blocksResolver' => [
+        'resolvedKey' => 'resolved'
+    ]
+];
+```
diff --git a/content/1.docs/3.headless/_dir.yml b/content/1.docs/3.headless/_dir.yml
new file mode 100644
index 0000000..219f31a
--- /dev/null
+++ b/content/1.docs/3.headless/_dir.yml
@@ -0,0 +1,2 @@
+title: Headless
+icon: i-ri-braces-fill
diff --git a/pages/docs.vue b/pages/docs.vue
index fa0193b..a0800c3 100644
--- a/pages/docs.vue
+++ b/pages/docs.vue
@@ -2,8 +2,6 @@
 import type { NavItem } from "@nuxt/content";
 
 const navigation = inject<Ref<NavItem[]>>("navigation", ref([]));
-// TODO: Remove when fixed upstream
-const _mapContentNavigation = mapContentNavigation;
 
 const links = computed(
   () => navigation.value.find((item) => item._path === "/docs")?.children ?? [],
@@ -19,7 +17,7 @@ const links = computed(
             <UContentSearchButton size="sm" />
           </template>
 
-          <UNavigationTree :links="_mapContentNavigation(links)" />
+          <UNavigationTree :links="mapContentNavigation(links)" default-open />
         </UAside>
       </template>