Write documentation content

Create one Markdown file for each question or task a reader needs to complete. Ginko Docs renders the frontmatter title and description above the body, then builds the table of contents from body headings.

Start with required frontmatter

Documentation pages require title and description:

---
title: Configure webhooks
description: Send signed events from Acme to an HTTPS endpoint.
---

Create an endpoint that accepts `POST` requests before you add it to Acme.

## Add an endpoint

Open the project settings and enter the public HTTPS URL.

## Check the signature

Read the signature header before processing the request body.

The theme uses title as the page's level-one heading and uses description for the page introduction, SEO metadata, and social cards. Do not repeat the title with a # heading in the body.

Keep each page focused

Open with the result, definition, or constraint. Put the working command or example before background details. Use sentence-case headings and direct instructions.

A task page should help the reader complete one outcome. Move broad explanation into a concept page and exhaustive option lists into reference pages.

Avoid filler such as “simply,” “obviously,” and “in conclusion.” The page already ends with previous and next controls, so finish on the final useful instruction or expected result.

Order files without changing URLs

Prefix sibling folders and files with numbers:

The numeric segments control the sidebar and previous/next order. Ginko removes them from public URLs.

Add images

Plain Markdown images are the default for screenshots and inline illustrations:

![Workspace prepared for an editorial planning session](/images/content-demo-workspace.jpg)

Local images render through Nuxt Image with lazy loading and responsive sizes, and open in the zoom dialog on click while images.zoom stays enabled in the app configuration. External URLs render unoptimized. Reach for the figure component instead when the image needs a caption, a bleed, or a fixed aspect ratio.

Label code examples

Add the real filename after the fence language so readers know where code belongs:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ["@lupinum/ginko-docs"],
});
```

Use the smallest example that proves the instruction. Include required imports and surrounding configuration when omitting them would make the example fail.

Collapse long examples

When a complete example must stay long, wrap it in the collapse component. The block clips at a fixed height with a "Show all lines" control; expanding removes the inner scroll area so the page scrolls normally:

::collapse

```ts [app/app.config.ts]
export default defineAppConfig({
  // …a complete configuration too long to show at once
});
```

::

Content that fits the collapsed height renders without the control, so the wrapper is safe on any example that may grow.