GitHub/quartz
1
0
Fork 2
mirror of https://github.com/jackyzha0/quartz.git synced 2026-03-22 05:55:42 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity
81b5d9d624
quartz/docs/layout.md
saberzero1 6f48471cde
feat(layout): page frames
2026-02-28 21:59:31 +01:00

9.3 KiB
Raw Blame History

title
Layout

Certain emitters may also output HTML files. To enable easy customization, these emitters allow you to fully rearrange the layout of the page.

In v5, the layout is defined in quartz.config.yaml using a defaults + byPageType structure.

  • defaults contains layout components shared across ALL page types (head, header, afterBody, footer).
  • byPageType contains per-page-type overrides (content, folder, tag, 404) for beforeBody, left, right sections, and optionally a template to control the page's #Page Frames.

Each page is composed of multiple different sections which contain QuartzComponents. The following code snippet lists all of the valid sections that you can add components to:

export interface FullPageLayout {
  head: QuartzComponent // single component
  header: QuartzComponent[] // laid out horizontally
  beforeBody: QuartzComponent[] // laid out vertically
  pageBody: QuartzComponent // single component
  afterBody: QuartzComponent[] // laid out vertically
  left: QuartzComponent[] // vertical on desktop and tablet, horizontal on mobile
  right: QuartzComponent[] // vertical on desktop, horizontal on tablet and mobile
  footer: QuartzComponent // single component
}

These correspond to following parts of the page:

Layout Preview
Desktop (width > 1200px) !quartz-layout-desktop.png
Tablet (800px < width < 1200px) !quartz-layout-tablet.png
Mobile (width < 800px) !quartz-layout-mobile.png

Note

There are two additional layout fields that are not shown in the above diagram.

  1. head is a single component that renders the <head> tag in the HTML. This doesn't appear visually on the page and is only is responsible for metadata about the document like the tab title, scripts, and styles.
  2. header is a set of components that are laid out horizontally and appears before the beforeBody section. This enables you to replicate the old Quartz 3 header bar where the title, search bar, and dark mode toggle. By default, Quartz doesn't place any components in the header.

Layout components are configured in the layout section of quartz.config.yaml. Plugins declare their position and priority, and the layout system arranges them automatically:

plugins:
  - source: github:quartz-community/explorer
    enabled: true
    layout:
      position: left
      priority: 50
  - source: github:quartz-community/graph
    enabled: true
    layout:
      position: right
      priority: 10
  - source: github:quartz-community/search
    enabled: true
    layout:
      position: left
      priority: 20
  - source: github:quartz-community/backlinks
    enabled: true
    layout:
      position: right
      priority: 30
  - source: github:quartz-community/article-title
    enabled: true
    layout:
      position: beforeBody
      priority: 10
  - source: github:quartz-community/content-meta
    enabled: true
    layout:
      position: beforeBody
      priority: 20
  - source: github:quartz-community/tag-list
    enabled: true
    layout:
      position: beforeBody
      priority: 30
  - source: github:quartz-community/footer
    enabled: true
    options:
      links:
        GitHub: https://github.com/jackyzha0/quartz
        Discord Community: https://discord.gg/cRFFHYye7t

layout:
  groups:
    toolbar:
      direction: row
      gap: 0.5rem
  byPageType:
    content: {}
    folder:
      exclude:
        - reader-mode
      positions:
        right: []
    tag:
      exclude:
        - reader-mode
      positions:
        right: []
    "404":
      positions:
        beforeBody: []
        left: []
        right: []

For advanced layout overrides using TypeScript (e.g. custom component wrappers or conditional logic), you can use the TS override in quartz.ts:

import { loadQuartzConfig, loadQuartzLayout } from "./quartz/plugins/loader/config-loader"

const config = await loadQuartzConfig()
export default config
export const layout = await loadQuartzLayout({
  defaults: {
    // override default layout for all page types
  },
  byPageType: {
    content: {
      // override layout for content pages only
    },
    folder: {
      // override layout for folder pages only
    },
  },
})

Fields defined in defaults can be overridden by specific entries in byPageType.

Community component plugins are installed via npx quartz plugin add github:quartz-community/<name>. See layout-components for built-in layout utilities (Flex, MobileOnly, DesktopOnly, etc.).

You can also checkout the guide on creating components if you're interested in further customizing the behaviour of Quartz.

Page Frames

Page frames control the overall HTML structure of a page — specifically, how the layout slots (sidebars, header, content, footer) are arranged inside the page shell. Different page types can use different frames to produce fundamentally different layouts.

Quartz ships with three built-in frames:

Frame Description Used by
default Three-column layout with left sidebar, center content (header, beforeBody, content, afterBody), right sidebar, and footer. This is the standard Quartz layout. ContentPage, FolderPage, TagPage, BasesPage
full-width No sidebars. Single center column spanning the full width with header, content, afterBody, and footer. —
minimal No sidebars, no header or beforeBody chrome. Only content and footer. NotFoundPage (404)

Plugins can also provide their own frames. For example, the canvas-page plugin ships a "canvas" frame that provides a fullscreen canvas with a togglable sidebar.

How frames are resolved

Each page type can declare a default frame in its plugin source code via the frame property. The resolution order is:

  1. YAML config override: layout.byPageType.<name>.template in quartz.config.yaml
  2. Plugin-registered frame: Frames registered by plugins via the Frame Registry (loaded from the plugin's frames export)
  3. Plugin declaration: The frame property set in the page type plugin's source code
  4. Fallback: "default"

For example, to override canvas pages to use the minimal frame:

layout:
  byPageType:
    canvas:
      template: minimal

Custom frames

There are two ways to provide custom frames:

1. Plugin-provided frames (recommended for reusable frames):

Plugins can ship their own frames by declaring them in package.json and exporting them from a ./frames subpath. See making plugins#Providing Custom Frames for details. When a plugin with frames is installed, its frames are automatically registered in the Frame Registry and available by name.

2. Core frames (for project-specific frames):

You can also create frames directly in quartz/components/frames/ by implementing the PageFrame interface and registering the frame in quartz/components/frames/index.ts. See the advanced/architecture for the full PageFrame interface.

Frames are applied as a data-frame attribute on the .page element, which you can target in CSS:

.page[data-frame="my-frame"] > #quartz-body {
  /* custom grid layout */
}

Frame CSS should be scoped with [data-frame="name"] selectors to avoid conflicts with other frames.

Layout breakpoints

Quartz has different layouts depending on the width the screen viewing the website.

The breakpoints for layouts can be configured in variables.scss.

  • mobile: screen width below this size will use mobile layout.
  • desktop: screen width above this size will use desktop layout.
  • Screen width between mobile and desktop width will use the tablet layout.
$breakpoints: (
  mobile: 800px,
  desktop: 1200px,
);

Style

Most meaningful style changes like colour scheme and font can be done simply through the configuration#General Configuration options. However, if you'd like to make more involved style changes, you can do this by writing your own styles. Quartz uses Sass for styling.

You can see the base style sheet in quartz/styles/base.scss and write your own in quartz/styles/custom.scss.

Note

Some components may provide their own styling as well! Community plugins bundle their own styles. If you'd like to customize styling for a specific component, double check the component definition to see how its styles are defined.