Qubik's Site

Frontmatter & Source-local Metadata Reference ​

Options that describe one page or one folder live with the content rather than in themeConfig — page frontmatter, an adjacent explorer.json, or a series' series.yml. This is the complete list of what the theme reads, with types, defaults, and examples. Site-wide options are in theme-config.md.

Fields marked LocalizableText take a plain string or a per-language map ({ en: "…", "zh-Hans": "…" }), resolved against the active UI language.

Quick reference ​

FieldTypeDefaultApplies to
titleLocalizableTextthe file/URL slugany page
explorerTitleLocalizableTexttitleany page
descriptionLocalizableTextauto excerptposts, series articles
datedate / string / numbernoneposts, series articles
updated / lastUpdateddate / string / numbergit timestamparticles
tagsstring | string[][]posts, series articles
categoriesstring | string[][]posts, series articles
coverstringnoneposts, series articles
ordernumber0any page, series articles
showInExplorerbooleantrueany page
homebooleanfalseany page
pageTypepage-type stringresolved from the pathany page
articlebooleantrueposts, series articles
licensebooleantruearticles
commentsbooleantruearticles

title ​

  • Type: LocalizableText
  • Default: the page's file/URL slug

The page title. It drives the explorer label, the browser tab, post-list cards, the archives rows, and the license card's article title — all of which re-resolve a map in place when the reader switches language.

yaml
yaml
---
title:
  en: Hello, Terminal
  zh-Hans: 你好，终端
---

A per-language map is resolved to the build language for the server-rendered <head>, then re-resolved client-side. That is handled for you; nothing extra to configure.

explorerTitle ​

  • Type: LocalizableText
  • Default: falls back to title

Overrides the explorer row label only, leaving the page's own title alone — useful when a long article title needs a short tree label.

yaml
yaml
---
title: "A Complete Tour of the Status Bar"
explorerTitle: "Status bar"
---

description ​

  • Type: LocalizableText
  • Default: the automatic excerpt (the body above the first --- separator)

The summary shown on post cards and in listings, and the page's meta description.

yaml
yaml
---
description:
  en: A first look at the theme.
  zh-Hans: 主题初识。
---

date ​

  • Type: a YAML date, an ISO string, or a millisecond timestamp
  • Default: none — the post sorts last and shows as undated

The publish date. It orders every listing (newest first) and fills the license card's "Published" row. Unzoned values are read as UTC and formatted in UTC for the server render, then in the reader's timezone once hydrated.

yaml
yaml
---
date: 2026-07-20
---

updated / lastUpdated ​

  • Type: a YAML date, an ISO string, or a millisecond timestamp
  • Default: VitePress's git-derived timestamp (requires lastUpdated: true in the site config)

Explicit last-updated date for the license card's "Updated" row; either spelling works, and an explicit value wins over the git timestamp. The row is omitted when neither is available.

yaml
yaml
---
updated: 2026-07-28
---

tags / categories ​

  • Type: string or string[]
  • Default: []

Taxonomy terms, authored as plain names — a single string is accepted as a one-element list. Slugs and /tags/…, /categories/… URLs derive from these names, so they never change with the UI language; display labels are localized site-wide through themeConfig.taxonomy.

yaml
yaml
---
tags: [theme, color]
categories: Design
---

cover ​

  • Type: string (site-absolute URL, typically under src/public/)
  • Default: none

A cover image. In post-list cards it becomes a full-height panel on the right that fades into the card (a full-width strip on top at mobile widths); on the article page the header becomes a hero banner showing the image in full. Covers are lazy-loaded, and pages without one render exactly as before.

yaml
yaml
---
cover: /images/demo-terminal-1.svg
---

order ​

  • Type: number (any finite value — negatives and fractions included)
  • Default: 0

Two uses, both "smaller sorts higher":

  • In the explorer, it orders a page or folder among its siblings. Ties keep the default folders-first-then-name sort, so untouched trees are unchanged. A negative value pins an entry above the unnumbered 0 siblings without renumbering them.
  • In a series, it orders the articles on the landing page.

Non-numeric or non-finite values are ignored (treated as 0).

yaml
yaml
---
order: -1
---

A folder takes its order from its explorer.json (which wins) or its index.md frontmatter.

showInExplorer ​

  • Type: boolean
  • Default: true

false hides the page from the explorer tree. It still builds and stays reachable by URL — this is a navigation filter, not a privacy control. On a folder's index.md it drops just the folder link; to hide the whole subtree, use the folder's explorer.json.

yaml
yaml
---
showInExplorer: false
---

home ​

  • Type: boolean
  • Default: false

Renders the page as the home page — the single welcome card configured by themeConfig.home.

yaml
yaml
---
home: true
title: home
---

pageType ​

  • Type: 'home' | 'normal' | 'post' | 'series' | 'listing' | 'notFound'
  • Default: resolved from the page's location under src/

The escape hatch for the automatic page-type dispatch — set it only when a page must render as a type its path does not imply. Normal resolution order is: not-found → this override → home → listing paths → article: false → series/ and posts/ prefixes → normal. See design/content-architecture.md §3–4.

yaml
yaml
---
pageType: listing
---

article ​

  • Type: boolean
  • Default: true

article: false drops a page under posts/ or series/ out of the article chrome entirely — it renders as a plain normal page (no byline, license card, or comments).

yaml
yaml
---
article: false
---

license / comments ​

  • Type: boolean
  • Default: true

Individually drop the end-of-article license card or comment card. comments has no effect when no comment server is configured; the card is absent either way.

yaml
yaml
---
license: false
comments: false
---

explorer.json — folder metadata ​

An optional file placed beside a folder's Markdown children configures that folder in the auto-discovered explorer, without requiring an index.md and without touching the site config.

FieldTypeDefaultNotes
titleLocalizableTextfolder name, or the index page's titleFolder label
showInExplorerbooleantruefalse hides the folder and everything below it
ordernumber0Sibling order; wins over the index.md frontmatter order
json
json
{
  "title": { "en": "Advanced", "zh-Hans": "进阶" },
  "order": 1,
  "showInExplorer": true
}

series.yml — series metadata ​

One optional file per series folder (src/series/<slug>/series.yml). Every field is optional; the folder name is the series' identity and URL segment regardless.

FieldTypeDefaultNotes
iconLocalizableTextnoneFont Awesome or Nerd Font nf-* class list
titleLocalizableTextthe folder nameShown on the index and article banner
descriptionLocalizableTextnoneShown on the index and article banner
ordernumber0Position on the series index; ties sort alphabetically by slug
yaml
yaml
icon: nf-fa-terminal
title:
  en: Terminal Internals
  zh-Hans: 终端内幕
description:
  en: A short series on how the theme's shell is built.
order: 0

The full rationale for this layout is in design/content-architecture.md §5.

Qubik's SiteCustomizable Footer Content
READ~/docs/configuration/frontmatter
TOPdark