Skip to main content
Quartz layouts are configured in quartz.layout.ts, which defines component placement across different page types. Layouts control where components like navigation, table of contents, and search appear on your pages.

​
Layout Structure

Quartz supports two layout configurations:
  1. Shared Layout - Components that appear on all pages
  2. Page Layouts - Components specific to page types (content pages vs. list pages)
quartz.layout.ts
import { PageLayout, SharedLayout } from "./quartz/cfg"
import * as Component from "./quartz/components"

// Shared across all pages
export const sharedPageComponents: SharedLayout = {
  head: Component.Head(),
  header: [],
  afterBody: [],
  footer: Component.Footer(),
}

// For single content pages
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [/* ... */],
  left: [/* ... */],
  right: [/* ... */],
}

// For list pages (tags, folders)
export const defaultListPageLayout: PageLayout = {
  beforeBody: [/* ... */],
  left: [/* ... */],
  right: [/* ... */],
}

​
Shared Layout

Components in SharedLayout appear on every page of your site.

​
Structure

​
head
Component
Content injected into the <head> tag (meta tags, scripts, styles)
​
header
Component[]
Components displayed at the top of every page
​
afterBody
Component[]
Components displayed after the main content
​
footer
Component
Footer component at the bottom of every page

​
Example

quartz.layout.ts
export const sharedPageComponents: SharedLayout = {
  head: Component.Head(),
  header: [],
  afterBody: [],
  footer: Component.Footer({
    links: {
      GitHub: "https://github.com/jackyzha0/quartz",
      "Discord Community": "https://discord.gg/cRFFHYye7t",
    },
  }),
}
The Head component is required for proper page functionality. Always include it in the shared layout.

​
Page Layouts

Page layouts define component placement for specific page types. Quartz uses a three-column grid:
  • left - Left sidebar (navigation, search)
  • center - Main content area
  • right - Right sidebar (table of contents, graph)
Additionally, beforeBody components appear above the main content.

​
Content Page Layout

Used for individual pages like notes and articles.
quartz.layout.ts
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ConditionalRender({
      component: Component.Breadcrumbs(),
      condition: (page) => page.fileData.slug !== "index",
    }),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Flex({
      components: [
        {
          Component: Component.Search(),
          grow: true,
        },
        { Component: Component.Darkmode() },
        { Component: Component.ReaderMode() },
      ],
    }),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}

​
Component Breakdown

beforeBody (above content):
  • Breadcrumbs - Navigation path (hidden on index page)
  • ArticleTitle - Page title heading
  • ContentMeta - Metadata (dates, reading time)
  • TagList - Tags associated with the page
left (left sidebar):
  • PageTitle - Site title/logo
  • Spacer - Spacing on mobile devices
  • Flex - Horizontal layout containing Search, Darkmode toggle, and ReaderMode
  • Explorer - File tree navigation
right (right sidebar):
  • Graph - Interactive graph view of connections
  • TableOfContents - Page outline (desktop only)
  • Backlinks - Pages linking to this page

​
List Page Layout

Used for tag pages, folder indexes, and other collection views.
quartz.layout.ts
export const defaultListPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
    Component.ContentMeta(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Flex({
      components: [
        {
          Component: Component.Search(),
          grow: true,
        },
        { Component: Component.Darkmode() },
      ],
    }),
    Component.Explorer(),
  ],
  right: [],
}
List pages typically have an empty right sidebar to provide more space for the content list.

​
Layout Components

​
Conditional Rendering

Show or hide components based on page properties: 
Component.ConditionalRender({
  component: Component.Breadcrumbs(),
  condition: (page) => page.fileData.slug !== "index",
})
​
component
Component
required
The component to conditionally render
​
condition
(page: QuartzPluginData) => boolean
required
Function that returns true to show the component, false to hide it

​
Responsive Components

Control component visibility by screen size: 
Component.DesktopOnly(Component.TableOfContents())
Only visible on desktop screens (> 1024px)

​
Flex Layout

Arrange components horizontally: 
Component.Flex({
  components: [
    {
      Component: Component.Search(),
      grow: true,
    },
    { Component: Component.Darkmode() },
    { Component: Component.ReaderMode() },
  ],
})
​
components
FlexComponent[]
required
Array of components with optional grow property
​
grow
boolean
default:false
If true, the component expands to fill available space

​
Common Components

​
PageTitle
Component
Site title/logo, typically links to the homepage
​
Breadcrumbs
Component
Navigation path showing the page hierarchy
​
Explorer
Component
File tree navigation for browsing content structure

​
Content

​
ArticleTitle
Component
Page heading (h1) displaying the page title
​
ContentMeta
Component
Metadata like creation date, modification date, and reading time
​
TagList
Component
List of tags associated with the current page
​
TableOfContents
Component
Outline of page headings for quick navigation

​
Discovery

​
Search
Component
Full-text search across all content
​
Graph
Component
Interactive visualization of page connections
​
Backlinks
Component
List of pages that link to the current page

​
Utilities

​
Darkmode
Component
Toggle between light and dark color schemes
​
ReaderMode
Component
Distraction-free reading mode
​
Spacer
Component
Empty space for layout purposes

​
Customizing Layouts

​
Adding a Component

To add a component to your layout:
  1. Import the component (already done via import * as Component)
  2. Add it to the appropriate section:
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ArticleTitle(),
    Component.ContentMeta(),
    // Add your component here
  ],
  left: [/* ... */],
  right: [/* ... */],
}

​
Reordering Components

Simply change the order in the array: 
beforeBody: [
  Component.ArticleTitle(),      // Appears first
  Component.TagList(),           // Then tags
  Component.ContentMeta(),       // Then metadata
]

​
Removing a Component

Delete or comment out the component: 
left: [
  Component.PageTitle(),
  // Component.Explorer(),  // Removed file tree
  Component.Search(),
]

​
Layout Examples

export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ArticleTitle(),
  ],
  left: [
    Component.PageTitle(),
    Component.Search(),
  ],
  right: [],
}
Focused on content with minimal distractions.
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.Breadcrumbs(),
    Component.ArticleTitle(),
  ],
  left: [
    Component.PageTitle(),
    Component.Search(),
    Component.Explorer(),
  ],
  right: [
    Component.TableOfContents(),
  ],
}
Ideal for structured documentation with clear navigation.
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ArticleTitle(),
    Component.TagList(),
    Component.ContentMeta(),
  ],
  left: [
    Component.PageTitle(),
    Component.Search(),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.Backlinks(),
  ],
}
Emphasizes connections and relationships between notes.

​
Best Practices

Keep it Balanced

Distribute components evenly across left and right sidebars to avoid overwhelming one side.

Mobile First

Use MobileOnly and DesktopOnly to ensure good experience on all devices.

Content Priority

Place most important navigation in the left sidebar where users look first.

Consistent Layouts

Maintain similar layouts between content and list pages for familiarity.

Site Settings

Configure page title, locale, and behavior

Theme Configuration

Customize colors, fonts, and visual styling

Build docs developers (and LLMs) love

Get started for freeTalk to us