Frontmatter and data schemas

Exact docs, blog, author, and navigation fields accepted by the generated strict collections.

The generated collections validate every source with strict: true. Fields listed as required must be present and must have the exact value type shown here.

Documentation pages

Docs are Markdown files in the generated docs collection.

Field	Type	Required	Purpose
`title`	`string`	Yes	Page title, metadata, and default navigation label
`description`	`string`	Yes	Page description and search/SEO summary
`icon`	`string`	No	Page or navigation icon metadata
`badge`	`string`	No	Short navigation badge
`updated`	`string`	No	Visible last-updated line, sitemap `lastmod`, agent metadata, and `TechArticle.dateModified`
`redirectFrom`	`string[]`	No	Former public URLs that permanently redirect to this page
`sidebar`	`'section' \| 'group'`	No	Structural sidebar role; nested navigation is preferred for pages
`navigation`	`object`	No	Page-specific navigation metadata

The navigation object accepts only these fields. The docs schema accepts this object, but not navigation: false:

Field	Type	Required
`navigation.title`	`string`	No
`navigation.icon`	`string`	No
`navigation.badge`	`string`	No
`navigation.sidebar`	`'section' \| 'group'`	No

Write the object as nested YAML:

content/docs/1.installation.md

---
title: Install Ginko Docs
description: Add the layer to an existing Nuxt application.
updated: "2026-07-21"
navigation:
  title: Installation
  icon: lucide:package-plus
  badge: Start
---

Install the package in the consuming application.

updated must be an ISO date (YYYY-MM-DD). When present, the page footer renders a localized last-updated line and the sitemap entry carries a matching lastmod.

Moved pages

When a page moves, keep its old URLs in redirectFrom. Entries are absolute site paths exactly as served, including the locale prefix and translated slug:

content/de/1.dokumentation/9.ressourcen/2.anforderungen-und-upgrades.md

---
title: Anforderungen und Upgrades
description: Unterstützte Paketbereiche und Upgrade-Prüfungen.
redirectFrom:
  - /de/dokumentation/ressourcen/upgrade-anleitung
---

The build prerenders each old path as a permanent redirect to the page's current route, and server deployments answer with HTTP 301. Old paths never enter the sitemap. The build fails when a redirectFrom entry collides with a live page, another page's redirect, or a theme route. On static hosting the stub is served as a meta refresh document rather than a true 301 status.

Publication controls

draft is a core-owned field removed before the custom strict schema runs. Docs and blog pages may therefore set draft: true. Drafts remain visible in development and are excluded from public production surfaces.

Files or directories with an underscore prefix are partials. They can supply content to other processing, but they do not become public pages, navigation entries, or agent entries.

Use .navigation.yml for a directory that should become a sidebar section or group:

content/en/1.docs/7.reference/.navigation.yml

title: Reference
icon: lucide:braces
sidebar: section

Field	Accepted type	Effect
`title`	`string`	Visible title of the structural node
`description`	`string`	Optional node description
`order`	`number`	Explicit sort order
`icon`	`string \| false`	Set or suppress the icon
`badge`	`string \| object`	Badge text or structured badge metadata
`hidden`	`boolean`	Hide the node from navigation
`navigation`	`false \| object`	Disable navigation or set navigation metadata
`sidebar`	`'section' \| 'group'`	Render the node as a section or group

content/en/1.docs/6.operations/.navigation.yml

title: Operations
icon: lucide:cloud-cog
sidebar: group

sidebar: section creates a section in the docs switcher. sidebar: group creates a labeled group inside the current section. Keep structural metadata in the directory file and page metadata in the page's nested navigation object.

Blog posts

The blog collection exists only with blog: true.

Field	Type	Required	Purpose
`title`	`string`	Yes	Article title
`description`	`string`	Yes	Article summary and metadata
`badge`	`string`	No	Short article label
`date`	`string`	Yes	Publication value shown by the blog UI, feed `pubDate`, and sitemap `lastmod`
`readingTime`	`string`	Yes	Authored reading-time label
`author`	Reference to `authors`	Yes	Path-like author record reference
`image`	`string`	No	Article image URL or public path
`redirectFrom`	`string[]`	No	Former public URLs that permanently redirect to this article

content/en/2.blog/product-update.md

---
title: Product update
description: What changed in the July release.
badge: Release
date: "2026-07-21"
readingTime: 4 min read
author: authors/ginko-docs-team
image: /images/july-release.png
---

The July release improves ...

The factory does not calculate readingTime; date must be an ISO date (YYYY-MM-DD). Blog posts do not accept the docs-only navigation or sidebar fields.

Author records

Authors are JSON files in the data-only authors collection.

Field	Type	Required
`slug`	`string`	Yes
`name`	`string`	Yes
`role`	`string`	Yes
`bio`	`string`	Yes
`avatar`	`string`	Yes
`links`	`Array<{ label: string; href: string }>`	No

content/en/authors/ginko-docs-team.json

{
  "slug": "ginko-docs-team",
  "name": "Ginko Docs Team",
  "role": "Documentation engineering",
  "bio": "The team maintains the product documentation.",
  "avatar": "/images/authors/ginko-docs-team.png",
  "links": [
    {
      "label": "GitHub",
      "href": "https://github.com/example"
    }
  ]
}

An authored blog reference omits the file extension: authors/ginko-docs-team. In a localized site, place the referenced author record in the corresponding locale tree.

Header and mobile-menu links are configured in app/app.config.ts, not in content frontmatter. A custom link has this schema:

GinkoDocsLink

interface GinkoDocsLink {
  label: { en: string; de?: string };
  to: { en: string; de?: string };
  icon?: string;
  description?: { en: string; de?: string };
}

Set ginkoDocs.nav.links to 'auto' to derive Documentation and the optional Blog link, or provide an array of this shape to replace the generated navigation.