Horizontal Rules

Markdown’s --- gives you a plain horizontal rule, but documentation sites often need something more expressive. Examples might include: a chapter divider, a gradient accent that matches your navbar, a decorative ornament between sections, or a labeled break that tells readers “Part Two starts here.”

The {{< hr >}} shortcode turns the humble <hr> into a flexible design tool. It supports four line styles, eight palette colors (plus any custom CSS color), adjustable thickness and width, text labels embedded in the rule, and nine ready-made presets.

Quick Start

Drop a shortcode into any .qmd page to get a styled rule:

{{< hr >}}

That gives you a 2px solid line at full width. To make it more interesting:

{{< hr preset="gradient-shimmer" >}}

Line Styles

Four border styles are available via the style parameter:

{{< hr style="solid" >}}
{{< hr style="dashed" >}}
{{< hr style="dotted" >}}
{{< hr style="double" >}}

Solid (default):

Dashed:

Dotted:

Double:

Colors

Palette Colors

Great Docs ships with eight gradient palette presets. Each one maps to a distinct color that adapts to dark mode automatically:

Name Light Dark Example
sky Deep blue Bright sky
peach Warm orange Soft peach
prism Rich purple Soft violet
lilac Bright lilac Light purple
slate Cool gray Light slate
honey Golden amber Bright gold
dusk Indigo Soft indigo
mint Teal Bright mint

Custom Colors

Any CSS color value works (hex codes, named colors, rgb(), or hsl()):

{{< hr color="#e11d48" >}}
{{< hr color="#16a34a" >}}
{{< hr color="#2563eb" >}}

Colored Line Styles

Colors combine naturally with line styles:

{{< hr style="dashed" color="#e11d48" >}}
{{< hr style="dotted" color="#2563eb" >}}

Thickness

Control the line weight with named values or exact pixel sizes:

Value Pixels
thin 1px
medium 2px (default)
thick 4px 
{{< hr thickness="thin" >}}
{{< hr >}}
{{< hr thickness="thick" >}}
{{< hr thickness="6px" >}}

Width and Alignment

By default, rules span the full container width. Use width to make them narrower, and align to position them when they don’t fill the container:

{{< hr width="75%" >}}
{{< hr width="50%" align="center" >}}
{{< hr width="50%" align="left" >}}
{{< hr width="50%" align="right" >}}

The width parameter accepts any CSS length or percentage. Use full as a shorthand for 100%.

Spacing

Control the vertical margin around the rule with the spacing parameter:

Value Margin
compact 1rem
normal 2rem (default)
spacious 4rem 
{{< hr spacing="compact" >}}
{{< hr spacing="spacious" >}}

Compact (1rem):

This is some text before the rule.

This is some text after the rule. Notice the tight spacing above and below.

Normal (2rem, default):

This is some text before the rule.

This is some text after the rule. This is the default amount of breathing room.

Spacious (4rem):

This is some text before the rule.

This is some text after the rule. The extra whitespace creates a clear section break.

Embedded Text

Place text or symbols in the center of a rule. The rule splits into two lines flanking the text:

{{< hr text="§" >}}
{{< hr text="Continue Reading" >}}
{{< hr text="★ ★ ★" >}}
§
Continue Reading
★ ★ ★

Text Size

The sizes sm, md (default), and lg are available:

{{< hr text="Small" text-size="sm" >}}
{{< hr text="Medium" >}}
{{< hr text="Large" text-size="lg" >}}
Small
Medium
Large

Colored Text

Add text-color to style the label independently from the line, or use color to tint both at once:

{{< hr text="Warning" color="#e11d48" text-color="#e11d48" >}}
{{< hr text="Chapter One" color="#6366f1" >}}
Warning
Chapter One

Text with Width

Text rules respect width and align:

{{< hr text="Centered" width="70%" >}}
{{< hr text="Left" width="60%" align="left" >}}
Centered
Left

Presets

Presets are ready-made visual styles that go beyond what style and color can achieve. Use preset to apply one:

Gradient Shimmer

We can get a horizontal rule that animates with a gradient. It shimmers smoothly:

{{< hr preset="gradient-shimmer" >}}
Note

The shimmer animation respects prefers-reduced-motion. Users who prefer reduced motion will see a static gradient instead.

Gradient Static

The same gradient palette without animation:

{{< hr preset="gradient-static" >}}

Fade

Full opacity at center, fading to transparent at both edges:

{{< hr preset="fade" >}}

Fade Edges

Transparent edges blooming into a colored center:

{{< hr preset="fade-edges" >}}

Dots

Three centered dots form a classic section break (with no line):

{{< hr preset="dots" >}}

Diamond

A diamond ornament flanked by fading lines:

{{< hr preset="diamond" >}}

Ornament

An elegant fleuron (❧) between fading lines:

{{< hr preset="ornament" >}}

Wave

A subtle repeating diagonal pattern:

{{< hr preset="wave" >}}

Double Line

Two parallel thin lines with a gap between them:

{{< hr preset="double-line" >}}

Combining Options

Presets define the visual pattern, but width, align, spacing, and color can still be overridden on top:

{{< hr preset="gradient-shimmer" width="60%" >}}
{{< hr preset="fade" width="50%" spacing="spacious" >}}
{{< hr preset="dots" color="#e11d48" >}}
{{< hr preset="ornament" width="60%" spacing="spacious" >}}

Style, color, and sizing options also combine freely:

{{< hr style="dashed" color="peach" width="75%" thickness="thick" >}}
{{< hr style="dotted" color="#2563eb" width="40%" thickness="thin" align="right" >}}

Real-World Patterns

Here are some common documentation patterns and how to achieve them:

Blog-style section break:

{{< hr preset="dots" spacing="spacious" >}}

Chapter divider with label:

{{< hr text="Chapter Two" color="#6366f1" thickness="thick" width="80%" >}}
Chapter Two

Elegant page separator:

{{< hr preset="ornament" width="60%" spacing="spacious" >}}

API section boundary:

{{< hr preset="gradient-shimmer" >}}

Light decorative pause:

{{< hr preset="fade" thickness="thin" width="50%" >}}

Parameter Reference

Parameter Values Default Description
style solid, dashed, dotted, double solid Line style
color Palette name, hex, CSS color Site accent Line color
thickness thin, medium, thick, or CSS value medium (2px) Line weight
width full, percentage, or CSS length 100% Horizontal extent
align center, left, right center Position when width < 100%
spacing compact, normal, spacious normal (2rem) Vertical margin
text Any string — Text centered on the rule
text-size sm, md, lg md Size of embedded text
text-color Hex or CSS color Inherits color Text label color
preset See Presets — Ready-made visual style

Dark Mode

All colors adapt automatically in dark mode. Palette colors switch to brighter variants for visibility on dark backgrounds, and the overall opacity is reduced slightly for a softer look. Custom hex colors are preserved as-is but receive a subtle opacity adjustment.

No extra configuration is needed as the shortcode works identically in both modes.

Next Steps

Horizontal rules provide visual separation between sections of content. The shortcode gives you control over style, color, thickness, and spacing, with presets for common patterns.