Qubik's Site

Navigation & Chrome ​

The shell around your content: the tool bar, the file explorer, the article table of contents, the find palette, the status bar, and the settings window. This page is about configuring and using them. What they look like and why is in design/design-language.md §4 and design/ui-sketch.md.

The frame is fixed: only the viewport panel scrolls, so the bars and panels stay put while you read.

Tool bar ​

The bar across the top holds the site title, the navigation tabs, and the action icons. A built-in ~/home tab and the search and color-mode controls are always present; everything else is configuration.

ts
ts
toolbar: {
  nav: [
    {
      text: { en: "Guide", "zh-Hans": "指南" },
      link: "/guide/",
      icon: "fa-solid fa-book",
      items: [
        { text: "Getting Started", link: "/guide/getting-started", icon: "fa-solid fa-rocket" },
        { text: "Advanced", link: "/guide/advanced/", icon: "fa-solid fa-flask" },
      ],
    },
    { text: "Archives", link: "/archives", icon: "fa-solid fa-box-archive" },
  ],
  actions: [
    { icon: "fa-brands fa-github", link: "https://github.com/…", label: "GitHub" },
  ],
},
  • A tab highlights when the current page matches its link — or any of its children's links.
  • A tab with items opens a floating dropdown on hover or keyboard focus, and stays a link itself (so link is still required). Children are plain links; they don't nest further.
  • actions are extra icon slots before the built-in controls — the extension point for social links and external tools, without touching a component.
  • External links open in a new tab.

Overflow. When the bar can't show the title, tabs, and icons in full — a narrow window, a long site title, a translated tab set — the nav and all action icons move into a right-side drawer behind a [⋮] expander. Below 640 px this is always the case. Nothing to configure; it measures itself.

File explorer ​

The left panel is a NeoVim-style file browser. Turn it on with either an automatic tree or a hand-authored one:

ts
ts
explorer: "auto",

With "auto", every Markdown page below src/ appears: directories become folders, each index.md becomes its folder's link, and labels come from frontmatter. Unset (or an empty array) hides the explorer and its tool-bar toggle entirely.

The per-page controls all live with the content, not in the site config:

To…Do this
Label a pagetitle: in its frontmatter (localizable)
Label a page in the tree onlyexplorerTitle: in its frontmatter
Label a folder without an index.mdexplorer.json beside its children, with a title
Reorder siblingsorder: (smaller sorts higher; negatives pin above the default 0)
Hide a pageshowInExplorer: false in its frontmatter
Hide a folder and everything under it"showInExplorer": false in its explorer.json
json
json
{
  "title": { "en": "Advanced", "zh-Hans": "进阶" },
  "order": 1
}

Types and defaults for all of these: configuration/frontmatter.md.

Behavior. First-level folders start expanded and deeper ones collapsed; the route you're on temporarily reveals its ancestors; and any folder you toggle yourself is remembered across reloads. Clicking a folder's label opens its index page and expands it — clicking the chevron only toggles. The panel retracts from the tool bar's [=] control, and its width is drag-adjustable between 180 px and 420 px (arrow keys work when the handle has focus).

Below 640 px the explorer becomes an off-canvas drawer, dismissed by the close button, the backdrop, Esc, or navigating. In paper mode it is not rendered at all.

An explicit tree is still supported when you'd rather hand-author it:

ts
ts
explorer: [
  { text: "Guide", link: "/guide/", items: [
    { text: "Getting Started", link: "/guide/getting-started" },
  ] },
],

Article table of contents ​

The right-hand "on this page" panel is built from the rendered headings and follows the section you're reading. It is on by default:

ts
ts
toc: { enabled: true, minLevel: 2, maxLevel: 3, minHeadings: 2 },

It shows only on article pages that have at least minHeadings headings within the level range, never in paper mode or print, and is hidden below 1024 px. The [«] control retracts it to a reopen rail (remembered across reloads), and its width drags between 160 px and 400 px.

Each heading also carries a # control that copies its absolute URL to the clipboard and confirms with a transient toast.

Find palette ​

Press / (or use the tool-bar magnifier) to open the search window: an input pane over a results pane, ↑/↓ to move, Enter to open, Esc to close. The palette is the search UI — it queries Algolia directly and renders results in the theme's own window.

ts
ts
search: {
  algolia: {
    appId: "YOUR_APP_ID",
    apiKey: "YOUR_SEARCH_ONLY_API_KEY",
    indexName: "YOUR_INDEX",
  },
},

Use the search-only key. Without complete credentials the palette still opens and says search is not configured — nothing breaks.

Status bar ​

The bottom bar shows, left to right: the page state chip (HOME, READ, or 404) and the current location with a blinking cursor; then, on the right, the back-to-top button paired with reading progress, the language switcher, the color-mode indicator, the settings gear, and a live clock. Below 640 px the path and clock drop out and the remaining controls grow to full touch-target size.

Nothing here needs configuration; the mode indicator is an indicator only — the control that cycles dark → light → paper lives in the tool bar.

Settings window ​

The gear opens a two-pane floating window:

  • Fonts — content font family (Default / Sans / Serif / Mono) and size (Small / Medium / Large).
  • Language — switches the UI language in place.

Both persist, and the font choice is restored before first paint so there is no flash. Floating windows are a single shared instance: opening one replaces whatever was open, and any of them closes on the close control, a backdrop click, or Esc. Below 640 px they present as a near-full-screen sheet.

Keyboard ​

KeyDoes
/Open the find palette (ignored while typing in an input)
EscClose the floating window, the explorer drawer, or the nav drawer
↑ ↓ EnterMove through and open search results
← → Home EndResize a sidebar while its drag handle has focus

What gets remembered ​

Reader preferences are stored in localStorage under ct- keys, and the ones that affect first paint are restored before it:

KeyHolds
ct-modeColor mode (dark default, light, paper)
ct-langUI language
ct-font-family / ct-font-sizeContent font preferences
ct-explorerExplorer retracted or not (desktop)
ct-explorer-nodesWhich folders are expanded
ct-explorer-width / ct-toc-widthSidebar widths
ct-tocTOC retracted or not (desktop)

Clearing site data resets a reader to the defaults — dark mode, the site's default language, an expanded shell.

Qubik's SiteCustomizable Footer Content
READ~/docs/guide/navigation
TOPdark