Higher-Order Layout Components

scope:

• Higher-order components wrap plugins/components for layout composition, responsive visibility, conditional rendering.
• Configure standard cases in quartz.config.yaml through layout properties.
• Use quartz.ts overrides for custom logic.

Flex Component

purpose:

• Creates flexbox layouts for child components.
• Arranges components in rows/columns.
• Supports responsive toolbars, grouped controls, proportional sizing.

YAML Configuration

mechanics:

• Define flex containers in top-level layout.groups.
• Assign plugins to a container with layout.group.
• Configure item behavior with layout.groupOptions.

quartz.config.yaml

plugins:
  - source: github:quartz-community/search
    enabled: true
    layout:
      position: left
      priority: 20
      group: toolbar
      groupOptions:
        grow: true # Search will grow to fill available space
  - source: github:quartz-community/darkmode
    enabled: true
    layout:
      position: left
      priority: 30
      group: toolbar # Darkmode keeps its natural size
  - source: github:quartz-community/reader-mode
    enabled: true
    layout:
      position: left
      priority: 35
      group: toolbar
 
layout:
  groups:
    toolbar:
      direction: row
      gap: 0.5rem

layout.groupOptions:

Option	Type	Description
grow	boolean	Grow into free main-axis space
shrink	boolean	Shrink when space requires
basis	string	Initial main size, e.g. "200px"
order	number	Flex item order
align	"start" | "end" | "center" | "stretch"	Cross-axis alignment
justify	"start" | "end" | "center" | "between" | "around"	Main-axis alignment

layout.groups:

Option	Type	Description
direction	"row" | "row-reverse" | "column" | "column-reverse"	Flex direction
wrap	"nowrap" | "wrap" | "wrap-reverse"	Flex wrapping
gap	string	Item gap, e.g. "0.5rem"

TS Override

usage:

• Use Component.Flex() in quartz.ts for full programmatic control.

quartz.ts (override)

Component.Flex({
  components: [
    {
      Component: Plugin.Search(),
      grow: true, // Search will grow to fill available space
    },
    { Component: Plugin.Darkmode() }, // Darkmode keeps its natural size
  ],
  direction: "row",
  gap: "1rem",
})

type FlexConfig = {
  components: {
    Component: QuartzComponent
    grow?: boolean
    shrink?: boolean
    basis?: string
    order?: number
    align?: "start" | "end" | "center" | "stretch"
    justify?: "start" | "end" | "center" | "between" | "around"
  }[]
  direction?: "row" | "row-reverse" | "column" | "column-reverse"
  wrap?: "nowrap" | "wrap" | "wrap-reverse"
  gap?: string
}

Overriding behavior

details:

• Components inside Flex receive the flex-component CSS class.
• flex-component adds display: flex.
• Override in custom CSS by setting display on .flex-component.

.flex-component {
  display: block; // or any other display type
}

MobileOnly / DesktopOnly Components

purpose:

• Controls plugin visibility by screen size.
• Enables mobile/desktop-specific layouts.

YAML Configuration

mechanics:

• Set layout.display on a plugin entry.

quartz.config.yaml

plugins:
  - source: github:quartz-community/table-of-contents
    enabled: true
    layout:
      position: right
      priority: 20
      display: desktop-only # Only visible on desktop

display values:

Value	Description
all	Visible at all screen sizes; default
mobile-only	Visible only on mobile
desktop-only	Visible only on desktop

TS Override

usage:

• Wrap components with Component.MobileOnly() or Component.DesktopOnly().

quartz.ts (override)

Component.MobileOnly(Component.Spacer())

quartz.ts (override)

Component.DesktopOnly(Plugin.TableOfContents())

ConditionalRender Component

purpose:

• Renders a component only when a page-specific condition passes.
• Supports dynamic layouts based on page properties.

YAML Configuration

mechanics:

• Set layout.condition on a plugin entry.
• Use built-in condition presets when possible.

quartz.config.yaml

plugins:
  - source: github:quartz-community/breadcrumbs
    enabled: true
    layout:
      position: beforeBody
      priority: 5
      condition: not-index # Hide breadcrumbs on the root index page

built-in_conditions:

Condition	Description
not-index	Render except on root index.md
has-tags	Render when frontmatter contains tags
has-backlinks	Render when the page has backlinks
has-toc	Render when the page has a table of contents

TS Override

usage:

• Use Component.ConditionalRender() in quartz.ts for custom conditions.

quartz.ts (override)

Component.ConditionalRender({
  component: Plugin.Search(),
  condition: (props) => props.displayClass !== "fullpage",
})

type ConditionalRenderConfig = {
  component: QuartzComponent
  condition: (props: QuartzComponentProps) => boolean
}

Tip

yaml_custom_conditions:

• Register custom YAML conditions with registerCondition() in a plugin initialization path.
• See making plugins.