Themes, Palettes, and Aesthetics ¶

markata-go makes it easy to customize your site’s appearance. You can go from zero configuration to a beautiful site, then progressively customize as needed.

Prerequisites: This guide assumes you’ve completed the Getting Started guide and have a working markata-go site.

Quick Start ¶ #

The fastest way to change your site’s look is to pick a color palette:

[markata-go.theme]
palette = "catppuccin-mocha"

That’s it! Your entire site now uses the Catppuccin Mocha color scheme.

Available Palettes ¶ #

markata-go includes 10 built-in color palettes. Use markata-go palette list to see them all:

Palette	Variant	Description
`default-light`	light	Clean, minimal light theme
`default-dark`	dark	Clean, minimal dark theme
`catppuccin-mocha`	dark	Soothing pastel colors, high contrast
`catppuccin-latte`	light	Soothing pastel colors, light variant
`nord-dark`	dark	Arctic, north-bluish colors
`gruvbox-dark`	dark	Retro groove, warm colors
`dracula`	dark	Vibrant purple on dark
`rose-pine`	dark	Soho vibes, natural colors
`solarized-dark`	dark	Scientifically designed colors
`tokyo-night`	dark	Tokyo city lights inspired

Previewing Palettes ¶ #

Preview a palette before using it:

# Show palette colors and contrast info
markata-go palette info catppuccin-mocha

# Check WCAG accessibility compliance
markata-go palette check catppuccin-mocha

Configuration Levels ¶ #

markata-go supports progressive customization - start simple and add complexity only when needed.

Level 1: Just Pick a Palette ¶ #

[markata-go.theme]
palette = "dracula"

Level 2: Override Specific Colors ¶ #

Keep your palette but tweak a few colors:

[markata-go.theme]
palette = "nord-dark"

[markata-go.theme.variables]
"--color-primary" = "#88c0d0"
"--color-link" = "#8fbcbb"

Level 3: Add Custom CSS ¶ #

Add a custom CSS file that loads after the theme:

[markata-go.theme]
palette = "catppuccin-mocha"
custom_css = "my-styles.css"

Then create static/my-styles.css:

/* Override any theme styles */
.post-title {
  font-family: 'Georgia', serif;
}

.site-header {
  border-bottom: 2px solid var(--color-primary);
}

Level 4: Override Templates ¶ #

Override specific template files by creating them in your templates/ directory:

my-site/
├── templates/
│   └── partials/
│       └── footer.html    # Your custom footer
└── markata-go.toml

Your custom templates take precedence over theme templates.

Theme Configuration Reference ¶ #

Full configuration options:

[markata-go.theme]
# Theme name (currently only "default" is available)
name = "default"

# Color palette to use
palette = "catppuccin-mocha"

# CSS variable overrides
[markata-go.theme.variables]
"--color-primary" = "#8b5cf6"
"--color-background" = "#1a1a2e"
"--color-text" = "#eaeaea"
"--color-link" = "#06b6d4"
"--color-link-hover" = "#22d3ee"
"--content-width" = "800px"
"--font-family" = "'Inter', sans-serif"

# Custom CSS file (relative to static/ directory)
custom_css = "custom.css"

Available CSS Variables ¶ #

These CSS custom properties can be overridden:

Variable	Description	Default
`--color-background`	Page background	Depends on palette
`--color-text`	Body text	Depends on palette
`--color-primary`	Primary accent color	Depends on palette
`--color-link`	Link color	Depends on palette
`--color-link-hover`	Link hover color	Depends on palette
`--color-border`	Border color	Depends on palette
`--color-code-bg`	Code block background	Depends on palette
`--content-width`	Max content width	`720px`
`--font-family`	Body font	System fonts
`--font-family-mono`	Code font	Monospace fonts
`--article-progress-height`	Sticky article progress bar height	`4px`
`--article-progress-track`	Background for the empty progress track	`color-mix(in srgb, var(--color-text) 90%, transparent 60%)`
`--article-progress-start`	Gradient start color for the filled portion	`var(--color-primary)`
`--article-progress-end`	Gradient end color for the filled portion	`color-mix(in srgb, var(--color-primary) 40%, var(--color-primary-light, var(--color-primary)) 60%)`
`--article-progress-glow`	Glow color around the indicator	`color-mix(in srgb, var(--color-primary) 70%, transparent 50%)`

Article Reading Progress Indicator ¶ #

Each article page renders a slim, sticky progress track (.article-progress) that follows the reader as they scroll. The indicator is powered by the initArticleProgressIndicator script, which throttles scroll events with requestAnimationFrame and updates the fill amount by transforming .article-progress__indicator. The track is hidden on non-post pages and honors prefers-reduced-motion via CSS.

Override the CSS variables above to tune the look. Example:

[markata-go.theme.variables]
"--article-progress-height" = "5px"
"--article-progress-track" = "rgba(255, 255, 255, 0.35)"
"--article-progress-start" = "#facc15"
"--article-progress-end" = "#fb923c"
"--article-progress-glow" = "rgba(250, 204, 21, 0.8)"

Because the indicator is just another element in the post template, you can also restyle it by targeting .article-progress and .article-progress__indicator from a custom CSS file loaded via markata-go.theme.custom_css.

Dark Mode Support ¶ #

markata-go supports automatic dark/light mode switching based on user’s system preference.

Using Different Palettes for Light/Dark ¶ #

[markata-go.theme]
palette = "catppuccin-latte"        # Light mode
palette_dark = "catppuccin-mocha"   # Dark mode (prefers-color-scheme: dark)

The site automatically switches based on the visitor’s system settings.

Multi-Palette Theme Switcher ¶ #

Allow visitors to choose any available color palette at runtime through an interactive UI in the header. The switcher provides:

Dark/Light toggle: A sun/moon button to instantly switch between dark and light mode
Palette family selector: A dropdown to choose from palette families (Catppuccin, Gruvbox, Rose Pine, etc.)
Smart variant selection: Automatically picks the appropriate light/dark variant based on current mode
Keyboard shortcuts: ] next family, [ previous family, \ toggle dark/light mode
Toast notifications: Visual feedback when cycling through palettes

Enabling the Switcher ¶ #

[markata-go.theme]
palette = "rose-pine"  # Default palette

[markata-go.theme.switcher]
enabled = true
include_all = true  # Include all 70+ built-in palettes

When enabled, the switcher UI appears in the site header. Visitor selections are persisted in localStorage and restored on return visits.

Keyboard Shortcuts ¶ #

The palette switcher includes convenient keyboard shortcuts:

Key	Action
`]`	Switch to next palette family
`[`	Switch to previous palette family
`\`	Toggle dark/light mode

These shortcuts work anywhere on the page and show a toast notification with the new palette name.

Filtering Palettes ¶ #

By default, all discovered palettes are included. You can control which palettes appear:

Exclude specific palettes:

[markata-go.theme.switcher]
enabled = true
include_all = true  # Default
exclude = ["default-light", "default-dark"]  # Hide these palettes

Include only specific palettes:

[markata-go.theme.switcher]
enabled = true
include_all = false
include = ["catppuccin-mocha", "catppuccin-latte", "nord-dark", "nord-light"]

Switcher Configuration Reference ¶ #

Option	Type	Default	Description
`enabled`	boolean	`false`	Show the palette switcher UI
`include_all`	boolean	`true`	Include all discovered palettes
`include`	array	`[]`	Palettes to include (when `include_all` is false)
`exclude`	array	`[]`	Palettes to exclude (when `include_all` is true)
`position`	string	`"header"`	Where to place the switcher

How It Works ¶ #

Palette Manifest: When the switcher is enabled, markata-go generates a JSON manifest of all available palettes embedded in variables.css as a CSS custom property (--palette-manifest).
CSS Variables: Each palette’s colors are generated as CSS custom properties using [data-palette="palette-name"] selectors. When a user selects a palette, a data attribute is set on the <html> element.
JavaScript UI: The palette-switcher.js script (loaded conditionally when enabled):
- Reads the palette manifest from CSS
- Groups palettes into “families” (e.g., all Catppuccin variants)
- Creates the sun/moon toggle and family dropdown
- Handles keyboard shortcuts and persistence
Persistence: Selected palette family and dark/light preference are saved to localStorage and restored on page load.
Smart Variants: When you select a family like “Catppuccin”, the switcher automatically chooses catppuccin-latte in light mode and catppuccin-mocha in dark mode.

Styling the Switcher ¶ #

The switcher UI uses CSS custom properties for easy customization:

/* In your custom CSS */
:root {
  /* Toast notifications */
  --toast-bg: var(--color-surface);
  --toast-text: var(--color-text);
  --toast-border: var(--color-border);

  /* Mode toggle button */
  --toggle-size: 2rem;
  --toggle-bg: var(--color-surface);
  --toggle-hover-bg: var(--color-surface-hover);

  /* Family dropdown */
  --dropdown-bg: var(--color-surface);
  --dropdown-border: var(--color-border);
}

The switcher container can also be styled:

.palette-switcher {
  /* Container styles */
  gap: 0.5rem;
}

.palette-family-select {
  /* Dropdown styles */
  min-width: 120px;
}

.mode-toggle {
  /* Sun/moon button styles */
  border-radius: 50%;
}

Hide on Mobile ¶ #

To hide the family dropdown on mobile (keeping only the dark/light toggle):

@media (max-width: 768px) {
  .palette-family-select {
    display: none;
  }
}

JavaScript API ¶ #

The switcher exposes a JavaScript API for programmatic control:

// Get the current palette info
const current = PaletteSwitcher.getCurrentPalette();
// { family: "catppuccin", variant: "mocha", isDark: true }

// Set a specific palette
PaletteSwitcher.setPalette("rose-pine-moon");

// Toggle dark/light mode
PaletteSwitcher.toggleDarkMode();

// Get current dark mode state
const isDark = PaletteSwitcher.isDarkMode();

// Get all palette families
const families = PaletteSwitcher.getFamilies();
// ["catppuccin", "gruvbox", "rose-pine", ...]

Event Handling ¶ #

Listen for palette and mode changes:

// Palette family changed
window.addEventListener('palette-family-change', (e) => {
  console.log('Family:', e.detail.family);
  console.log('Palette:', e.detail.palette);
});

// Dark/light mode toggled
window.addEventListener('dark-mode-change', (e) => {
  console.log('Dark mode:', e.detail.isDark);
});

Palette CLI Commands ¶ #

List All Palettes ¶ #

markata-go palette list

Output:

NAME                      VARIANT  SOURCE     DESCRIPTION
----------------------------------------------------------------------
Catppuccin Mocha          dark     builtin    Soothing pastel theme
Catppuccin Latte          light    builtin    Soothing pastel theme (light)
Nord Dark                 dark     builtin    Arctic, north-bluish
...

Get Palette Info ¶ #

markata-go palette info catppuccin-mocha

Shows all colors in the palette with their hex values.

Check Accessibility ¶ #

markata-go palette check catppuccin-mocha

Checks WCAG 2.1 AA contrast requirements for text readability.

Export Palette ¶ #

Export a palette to different formats:

# Export as CSS custom properties
markata-go palette export catppuccin-mocha --format css

# Export as SCSS variables
markata-go palette export catppuccin-mocha --format scss

# Export as JSON
markata-go palette export catppuccin-mocha --format json

# Export as Tailwind config
markata-go palette export catppuccin-mocha --format tailwind

Create New Palette ¶ #

Generate a starter palette file:

markata-go palette new my-palette

Creates palettes/my-palette.toml that you can customize.

Clone Existing Palette ¶ #

Clone an existing palette as a starting point for customization:

# Interactive mode - opens fuzzy picker to select a palette
markata-go palette clone

# Clone a specific palette by name
markata-go palette clone catppuccin-mocha

# Clone with explicit new name
markata-go palette clone catppuccin-mocha --name "my-custom-theme"

The cloned palette is saved to ~/.config/markata-go/palettes/ and includes:

All colors from the source palette
Semantic and component color mappings
A description noting the source palette

This is useful when you want to:

Start from a well-designed palette and make minor adjustments
Create variants of existing palettes (e.g., higher contrast)
Experiment without modifying the original

Fetch Palette from Lospec ¶ #

Import color palettes directly from Lospec.com, a popular source for pixel art and retro color palettes:

# Fetch a palette by URL
markata-go palette fetch https://lospec.com/palette-list/sweetie-16.txt

# Use a custom name
markata-go palette fetch https://lospec.com/palette-list/cheese-palette.txt --name "My Cheese"

# Save to a custom directory
markata-go palette fetch https://lospec.com/palette-list/tokyo-night.txt -o palettes/

The fetched palette is saved to your user palettes directory (~/.config/markata-go/palettes/) by default. markata-go automatically:

Downloads the color list from Lospec
Analyzes colors to determine if it’s a light or dark theme
Generates semantic mappings (text-primary, bg-primary, accent, etc.)
Caches the download to avoid repeated network requests

Example output:

Fetching palette from: https://lospec.com/palette-list/sweetie-16.txt
Palette saved to: /home/user/.config/markata-go/palettes/sweetie-16.toml

Palette details:
  Name:        Sweetie 16
  Variant:     dark
  Colors:      16
  Source:      https://lospec.com/palette-list/sweetie-16.txt

Semantic mappings:
  bg-primary      -> color0      (#1a1c2c)
  text-primary    -> color15     (#f4f4f4)
  accent          -> color8      (#b13e53)

Use this palette in your config:
  [markata-go.theme]
  palette = "sweetie-16"

Pick Palette Interactively ¶ #

Browse all available palettes in a full-screen interactive TUI with live color previews:

# Pick a palette and set it in your config (default)
markata-go palette pick

# Only print the name without updating config
markata-go palette pick --no-set

The picker shows a two-panel layout:

Left panel – Fuzzy-filterable list of all palettes with variant badges ([dark]/[light]). Type to filter, use arrow keys to navigate.
Right panel – Live preview of the highlighted palette showing color swatches, semantic roles, and a contrast preview block.

Press Enter to select a palette and set it in your config, or Esc to cancel.

Compose with other commands:

# View detailed info for the palette you pick (without setting it)
markata-go palette info "$(markata-go palette pick --no-set)"

# Pick, set, and rebuild
markata-go palette pick && markata-go build

Creating Custom Palettes ¶ #

Create a custom palette by adding a TOML file to palettes/ in your project:

# palettes/my-brand.toml
[palette]
name = "My Brand"
variant = "light"  # or "dark"
author = "Your Name"

# Raw colors
[palette.colors]
brand-primary = "#3b82f6"
brand-secondary = "#8b5cf6"
brand-accent = "#06b6d4"
white = "#ffffff"
gray-50 = "#f9fafb"
gray-100 = "#f3f4f6"
gray-700 = "#374151"
gray-800 = "#1f2937"
gray-900 = "#111827"

# Semantic mapping
[palette.semantic]
text-primary = "gray-800"
text-secondary = "gray-700"
bg-primary = "white"
bg-secondary = "gray-50"
accent = "brand-primary"
link = "brand-primary"
link-hover = "brand-secondary"

Then use it:

[markata-go.theme]
palette = "my-brand"

Aesthetics ¶ #

While palettes control colors, aesthetics control form and layout - the non-color design tokens that define your site’s visual personality.

Think of it this way: Palettes are what colors you use. Aesthetics are how things are shaped.

Quick Start ¶ #

Set an aesthetic in one line:

[markata-go]
aesthetic = "elevated"

Your entire site now uses generous rounded corners, layered shadows, and comfortable spacing.

Understanding the Separation ¶ #

Aspect	Palettes	Aesthetics
Controls	Colors	Shape, spacing, depth
Tokens	`--color-*` variables	`--radius-`, `--shadow-`, `--spacing-*`
Examples	Background, text, accent colors	Border radius, shadow depth, spacing scale
Switch	Changes color scheme	Changes visual “feel”

This separation means you can:

Use any palette with any aesthetic
Switch aesthetics without changing colors
Fine-tune form independently of color

Available Aesthetics ¶ #

markata-go includes 5 built-in aesthetics:

Aesthetic	Description	Best For
`balanced`	Default. Comfortable rounding, subtle shadows, normal spacing	General purpose, blogs
`brutal`	Sharp corners, thick borders, tight spacing, no shadows	Bold statements, portfolios
`minimal`	No rounding, maximum whitespace, no shadows, hairline borders	Documentation, reading-focused
`elevated`	Generous rounding, layered shadows, generous spacing	Premium/SaaS, card-heavy layouts
`precision`	Subtle corners, compact spacing, hairline borders, minimal shadows	Technical docs, data-heavy sites

Visual Comparison ¶ #

Brutal:

┌────────────────────────┐
│ No rounding            │
│ Thick 3px borders      │
│ Tight spacing          │
│ No shadows             │
└────────────────────────┘

Balanced (default):

╭────────────────────────╮
│ Subtle 4-8px rounding  │
│ Normal 1px borders     │
│ Standard spacing       │
│ Light shadows          │
╰────────────────────────╯

Elevated:

╭────────────────────────╮
│                        │
│ Generous 16px rounding │
│ Minimal borders        │
│ Generous spacing       │
│ Layered shadows ▓▒░    │
│                        │
╰────────────────────────╯

Configuration Examples ¶ #

Basic usage:

[markata-go]
aesthetic = "brutal"

Combine with a palette:

[markata-go]
aesthetic = "elevated"

[markata-go.theme]
palette = "catppuccin-mocha"

Override specific tokens:

[markata-go]
aesthetic = "balanced"

[markata-go.aesthetic_overrides]
border_radius = "12px"      # Override just the radius
shadow_intensity = 1.5      # Make shadows 50% stronger
spacing_scale = 1.1         # Slightly more spacing

Aesthetic Overrides Reference ¶ #

Fine-tune any aesthetic with these overrides:

Override	Type	Description	Example
`border_radius`	string	Base border radius	`"8px"`, `"0.5rem"`
`border_width`	string	Border thickness	`"1px"`, `"2px"`
`border_style`	string	Border style	`"solid"`, `"dashed"`, `"none"`
`spacing_scale`	float	Multiplier for spacing	`0.9` (tighter), `1.2` (looser)
`shadow_intensity`	float	Multiplier for shadow opacity	`0` (none), `1.5` (stronger)
`shadow_size`	string	Shadow size preset	`"sm"`, `"md"`, `"lg"`, `"none"`

Example: Make “balanced” more spacious:

[markata-go]
aesthetic = "balanced"

[markata-go.aesthetic_overrides]
spacing_scale = 1.25
shadow_intensity = 0.5  # Lighter shadows

Example: Soften “brutal”:

[markata-go]
aesthetic = "brutal"

[markata-go.aesthetic_overrides]
border_radius = "4px"   # Add slight rounding
border_width = "2px"    # Thinner borders

Aesthetic CLI Commands ¶ #

List all available aesthetics:

markata-go aesthetic list

Output:

Available aesthetics:
  brutal     - Brutalist design: harsh, uncompromising, raw
  precision  - Technical/engineering: clean, exact, minimal
  balanced   - Default harmonious: comfortable, balanced
  elevated   - Layered/premium: depth, floating cards
  minimal    - Maximum whitespace: sparse, intentional

Show details of a specific aesthetic:

markata-go aesthetic show elevated

Output:

Aesthetic: elevated
Description: Layered/premium: depth, floating cards

Tokens:
  radius:  0.5rem (sm), 0.75rem (md), 1rem (lg)
  spacing: 1.25x scale
  border:  none
  shadow:  0 4px 12px rgba(0,0,0,0.15)

CSS Preview:
  --radius-sm: 0.5rem;
  --radius-md: 0.75rem;
  --radius-lg: 1rem;
  --radius-full: 9999px;
  --shadow: 0 4px 12px rgba(0,0,0,0.15);

Creating Custom Aesthetics ¶ #

Create a custom aesthetic by adding a TOML file to aesthetics/ in your project:

# aesthetics/my-aesthetic.toml
name = "My Aesthetic"
description = "Custom design for my brand"

[tokens.radius]
none = "0"
sm = "6px"
md = "10px"
lg = "16px"
xl = "24px"
full = "9999px"

[tokens.spacing]
scale = 1.1

[tokens.border]
width_thin = "1px"
width_normal = "2px"
width_thick = "3px"
style = "solid"

[tokens.shadow]
sm = "0 1px 2px rgba(0,0,0,0.05)"
md = "0 4px 8px rgba(0,0,0,0.1)"
lg = "0 8px 16px rgba(0,0,0,0.12)"
xl = "0 16px 32px rgba(0,0,0,0.15)"

[tokens.typography]
font_primary = "var(--font-sans)"
leading_scale = 1.0

Then use it:

[markata-go]
aesthetic = "my-aesthetic"

Keyboard Shortcuts ¶ #

When the palette switcher is enabled, these shortcuts also work for aesthetics:

Key	Action
`]`	Next palette family
`[`	Previous palette family
`\`	Toggle dark/light mode

Template Overrides ¶ #

Override any template by placing it in your templates/ directory.

Template Search Order ¶ #

templates/ - Your project templates (highest priority)
themes/{theme}/templates/ - Theme templates
Embedded default templates (fallback)

Available Templates ¶ #

Template	Purpose
`base.html`	HTML skeleton, head, header, footer
`post.html`	Single post/article layout
`feed.html`	List of posts (index, archive, tags)
`card.html`	Post preview card in feeds
`partials/header.html`	Site header/navigation
`partials/footer.html`	Site footer
`partials/head.html`	Additional head content

Create templates/partials/footer.html:

<footer class="site-footer">
  <div class="container">
    <p>&copy; {{ now().year }} {{ config.title }}. Built with markata-go.</p>
    <nav>
      <a href="/about/">About</a>
      <a href="/contact/">Contact</a>
      <a href="https://github.com/yourusername">GitHub</a>
    </nav>
  </div>
</footer>

Static Assets ¶ #

Add custom CSS, JavaScript, images, and fonts to the static/ directory:

my-site/
├── static/
│   ├── css/
│   │   └── custom.css
│   ├── js/
│   │   └── analytics.js
│   ├── images/
│   │   └── logo.png
│   └── fonts/
│       └── MyFont.woff2
└── markata-go.toml

Files in static/ are copied directly to the output directory.

Reference them in templates:

<link rel="stylesheet" href="/css/custom.css">
<script src="/js/analytics.js"></script>
<img src="/images/logo.png" alt="Logo">

Per-Post Styling ¶ #

Override styles for specific posts using frontmatter:

---
title: "Special Post"
template: landing.html  # Use a different template
---

Or add custom CSS classes:

---
title: "Featured Article"
css_class: featured-post
---

Then style it:

.featured-post {
  background: linear-gradient(to right, var(--color-primary), var(--color-accent));
}

CSS Optimization ¶ #

markata-go automatically optimizes CSS loading by only including stylesheets that are actually needed for each page. This reduces page size and improves load times.

How It Works ¶ #

When rendering a page, markata-go scans the HTML content and detects which CSS features are used:

CSS File	Loaded When
`variables.css`	Always (core theme variables)
`main.css`	Always (core layout styles)
`components.css`	Always (navigation, footer, etc.)
`cards.css`	Feed/index pages with post cards
`admonitions.css`	Posts containing admonition blocks
`code.css`	Posts containing code blocks
`chroma.css`	Posts with syntax-highlighted code
`webmentions.css`	When webmentions are enabled
`palette-switcher.css`	When palette switcher is enabled
`search.css`	When search is enabled

Content Detection ¶ #

The CSS detection works by analyzing the rendered HTML:

Admonitions: Detected when class="admonition is present
Code blocks: Detected when syntax highlighting classes (class="chroma", class="highlight") or code elements (<pre><code, <code class="language-) are present
Cards: Included on feed pages (where feed variable exists in template context)

Benefits ¶ #

Smaller page sizes: Simple pages without code blocks or admonitions skip those CSS files
Faster load times: Less CSS to download and parse
Better caching: Core CSS files are shared across all pages

Custom CSS ¶ #

Your custom CSS (via theme.custom_css) is always loaded when configured. If you need conditional loading for custom styles, consider using CSS custom properties or JavaScript-based loading.

Media Borders and Gradient Effects ¶ #

markata-go provides beautiful, configurable borders for images and videos. From subtle solid borders to animated gradients, you have full control over how your media looks.

Default Media Styling ¶ #

By default, images and videos in your content get:

Rounded corners (--media-border-radius)
A subtle border (--media-border-width, --media-border-color)
Proper spacing and centering

Configuring Media Borders ¶ #

Customize the default borders via CSS variables:

/* In your custom CSS or via theme.variables */
:root {
  --media-border-width: 3px;      /* Border thickness */
  --media-border-color: #e5e7eb;  /* Border color */
  --media-border-radius: 0.5rem;  /* Corner rounding */
}

Or via config:

[markata-go.theme.variables]
"--media-border-width" = "4px"
"--media-border-color" = "#8b5cf6"
"--media-border-radius" = "1rem"

Gradient Borders ¶ #

Enable colorful gradient borders for a modern, eye-catching look. Add a class to your post content to enable gradients for all media:

---
title: "My Post with Gradient Borders"
css_class: gradient-borders
---

This applies the default accent gradient to all images and videos in that post.

Available Gradient Presets ¶ #

markata-go includes several beautiful gradient presets:

Class	Colors	Best For
`gradient-borders`	Primary to primary-dark	Brand-consistent
`gradient-vibrant`	Purple to pink	Creative, artistic
`gradient-warm`	Pink to orange	Energetic, warm
`gradient-cool`	Blue to cyan	Professional, tech
`gradient-sunset`	Pink to yellow	Warm, inviting
`gradient-ocean`	Teal to light blue	Calm, refreshing

Use them in frontmatter:

---
title: "Ocean-Themed Post"
css_class: gradient-ocean
---

Animated Gradient Borders ¶ #

For extra visual impact, use animated gradients that slowly shift colors:

---
title: "Attention-Grabbing Post"
css_class: gradient-animated
---

The animation cycles through purple, pink, and blue over 6 seconds.

Glow Effects ¶ #

Add a subtle glow behind your media:

---
title: "Glowing Media"
css_class: glow
---

Combine glow with gradients:

---
title: "Maximum Impact"
css_class: gradient-vibrant glow
---

Per-Image Styling ¶ #

For fine-grained control, add classes directly to images in your Markdown using HTML:

<img src="/images/hero.jpg" alt="Hero" class="gradient-vibrant glow">

Or use a wrapper div:

<div class="media-frame gradient-sunset glow">
  <img src="/images/featured.jpg" alt="Featured">
</div>

CSS Variable Reference for Media ¶ #

Variable	Description	Default
`--media-border-width`	Border thickness	`3px`
`--media-border-style`	Border style	`solid`
`--media-border-color`	Border color	`var(--color-border)`
`--media-border-radius`	Corner rounding	`0.5rem`
`--gradient-accent`	Default gradient	Primary colors
`--gradient-vibrant`	Purple-pink gradient	`#667eea` to `#f093fb`
`--gradient-warm`	Pink-orange gradient	`#f093fb` to `#f8b500`
`--gradient-cool`	Blue-cyan gradient	`#4facfe` to `#00f2fe`
`--gradient-sunset`	Pink-yellow gradient	`#fa709a` to `#fee140`
`--gradient-ocean`	Teal-blue gradient	`#2193b0` to `#6dd5ed`

Palette-Matching Gradients ¶ #

If you’re using a specific color palette, use the matching gradient for visual consistency:

Class	Palette	Colors
`gradient-catppuccin`	Catppuccin	Mauve → Pink → Red
`gradient-nord`	Nord	Frost colors (cyan → blue)
`gradient-dracula`	Dracula	Purple → Pink → Cyan
`gradient-gruvbox`	Gruvbox	Yellow → Orange → Red
`gradient-rose-pine`	Rosé Pine	Iris → Rose → Gold
`gradient-solarized`	Solarized	Blue → Cyan → Green
`gradient-tokyo-night`	Tokyo Night	Blue → Purple → Pink

Example: If your site uses catppuccin-mocha palette, use gradient-catppuccin for borders:

# markata-go.toml
[markata-go.theme]
palette = "catppuccin-mocha"

# In your post frontmatter
---
title: "Catppuccin-Styled Gallery"
css_class: gradient-catppuccin
---

Custom Gradients ¶ #

Create your own gradient by overriding the variables:

/* In static/custom.css */
:root {
  --gradient-accent: linear-gradient(135deg, #ff6b6b, #feca57, #48dbfb);
}

Or define a completely new one:

.post-content.gradient-custom img,
.post-content.gradient-custom video {
  border: none;
  padding: 3px;
  background: linear-gradient(45deg, #12c2e9, #c471ed, #f64f59);
  background-origin: border-box;
}

Then use in frontmatter:

---
css_class: gradient-custom
---

Dark Mode Considerations ¶ #

Gradient borders adapt to dark mode:

Glow effects become more prominent
Border colors adjust automatically
Gradients remain vibrant on dark backgrounds

Test your gradient choices in both light and dark mode.

Background Decorations ¶ #

Add multi-layered background decorations to your site for visual effects like snow, particles, stars, or animated elements.

Basic Configuration ¶ #

[markata-go.theme.background]
enabled = true

backgrounds = [
  { html = '<snow-fall count="200"></snow-fall>' },
]

scripts = ["/static/js/snow-fall.js"]

This adds a snow effect using a custom web component with its supporting JavaScript.

Multiple Layers ¶ #

Stack multiple background layers with different z-index values:

[markata-go.theme.background]
enabled = true

backgrounds = [
  { html = '<div class="stars"></div>', z_index = -20 },
  { html = '<div class="clouds"></div>', z_index = -10 },
  { html = '<snow-fall count="100"></snow-fall>', z_index = -5 },
]

scripts = ["/static/js/background-effects.js"]

css = '''
.stars {
  position: absolute;
  inset: 0;
  background: url("/images/stars.png") repeat;
  opacity: 0.3;
}

.clouds {
  position: absolute;
  inset: 0;
  background: url("/images/clouds.png") repeat-x;
  animation: drift 60s linear infinite;
}

@keyframes drift {
  from { background-position: 0 0; }
  to { background-position: 100% 0; }
}
'''

Configuration Reference ¶ #

Option	Type	Description
`enabled`	boolean	Enable/disable background decorations (default: false)
`backgrounds`	array	List of background elements
`backgrounds[].html`	string	HTML content for this layer
`backgrounds[].z_index`	integer	Stacking order (-1 is default, behind content)
`scripts`	array	Script URLs to load for background functionality
`css`	string	Custom CSS for styling background elements

Tips for Background Decorations ¶ #

Performance: Complex animations can impact performance. Test on lower-powered devices.
Accessibility: Ensure backgrounds don’t interfere with content readability. Use pointer-events: none (applied automatically).
Z-Index: Use negative values to place backgrounds behind content. Positive values overlay content.
Web Components: Custom elements like <snow-fall> provide encapsulated, reusable effects.
Reduced Motion: Consider respecting prefers-reduced-motion in your CSS:

@media (prefers-reduced-motion: reduce) {
  .background-layer * {
    animation: none !important;
  }
}

Example: Particle Background ¶ #

Using particles.js:

[markata-go.theme.background]
enabled = true

backgrounds = [
  { html = '<div id="particles-js"></div>' },
]

scripts = [
  "https://cdn.jsdelivr.net/particles.js/2.0.0/particles.min.js",
  "/static/js/particles-config.js",
]

css = '''
#particles-js {
  position: absolute;
  inset: 0;
}
'''

Seasonal Theme Calendar ¶ #

Automatically apply different themes based on the date. Perfect for seasonal decorations, holidays, or promotional periods.

Basic Configuration ¶ #

Enable date-based theme switching:

[markata-go.theme_calendar]
enabled = true

[[markata-go.theme_calendar.rules]]
name = "Christmas Season"
start_date = "12-15"
end_date = "12-26"
palette = "christmas"

[[markata-go.theme_calendar.rules]]
name = "Winter Frost"
start_date = "12-01"
end_date = "02-28"
palette = "winter-frost"

During December 15-26, the site uses the “christmas” palette. From December 1 to February 28, it uses “winter-frost” (excluding the more specific Christmas period).

How It Works ¶ #

First match wins: Rules are evaluated in order. The first matching rule is applied.
MM-DD format: Dates use month-day format (no year), so rules repeat annually.
Year boundary support: Ranges like 12-01 to 02-28 correctly span December through February.
Runs early: The calendar plugin runs at the Configure stage before other theme plugins, ensuring palette overrides are applied correctly.

Rule Configuration ¶ #

Each rule can override various theme settings:

[[markata-go.theme_calendar.rules]]
name = "Spooky October"
start_date = "10-01"
end_date = "10-31"
palette = "halloween"            # Single palette for both modes
# Or use separate light/dark palettes:
# palette_light = "halloween-light"
# palette_dark = "halloween-dark"

# CSS variable overrides
[markata-go.theme_calendar.rules.variables]
"--color-accent" = "#ff6600"
"--color-link" = "#9b59b6"

# Custom CSS file for the season
custom_css = "halloween.css"

Rule Options Reference ¶ #

Option	Type	Description
`name`	string	Display name for the rule (used in logs and CLI)
`start_date`	string	Start date in MM-DD format (e.g., “12-01”)
`end_date`	string	End date in MM-DD format (e.g., “02-28”)
`palette`	string	Palette to use (overrides both modes)
`palette_light`	string	Light mode palette (if different from dark)
`palette_dark`	string	Dark mode palette
`custom_css`	string	Additional CSS file for this period
`variables`	table	CSS variable overrides
`background`	table	Background decoration override (see below)
`font`	table	Font configuration override

Background Overrides ¶ #

Apply seasonal background decorations:

[[markata-go.theme_calendar.rules]]
name = "Winter Wonderland"
start_date = "12-01"
end_date = "02-28"
palette = "winter-frost"

[markata-go.theme_calendar.rules.background]
enabled = true
css = """
.snowflake {
  position: absolute;
  color: white;
  animation: fall linear infinite;
}
"""

[[markata-go.theme_calendar.rules.background.backgrounds]]
html = '<snow-fall count="100"></snow-fall>'
z_index = -5

Font Overrides ¶ #

Use a different font for special periods:

[[markata-go.theme_calendar.rules]]
name = "Christmas Season"
start_date = "12-15"
end_date = "12-26"
palette = "christmas"

[markata-go.theme_calendar.rules.font]
family = "Mountains of Christmas"
heading_family = "Snowburst One"
google_fonts = ["Mountains of Christmas", "Snowburst One"]

Multiple Rules Example ¶ #

Create a full year of seasonal themes:

[markata-go.theme_calendar]
enabled = true
default_palette = "catppuccin-mocha"  # Fallback when no rule matches

# Spring (March 20 - June 20)
[[markata-go.theme_calendar.rules]]
name = "Spring"
start_date = "03-20"
end_date = "06-20"
palette = "spring-garden"

# Summer (June 21 - September 22)
[[markata-go.theme_calendar.rules]]
name = "Summer"
start_date = "06-21"
end_date = "09-22"
palette = "summer-sunset"

# Halloween (October 15 - November 1)
[[markata-go.theme_calendar.rules]]
name = "Halloween"
start_date = "10-15"
end_date = "11-01"
palette = "spooky"

# Fall (September 23 - December 20, but after Halloween ends)
[[markata-go.theme_calendar.rules]]
name = "Fall"
start_date = "11-02"
end_date = "12-20"
palette = "autumn-leaves"

# Also need early fall before Halloween
[[markata-go.theme_calendar.rules]]
name = "Early Fall"
start_date = "09-23"
end_date = "10-14"
palette = "autumn-leaves"

# Winter (December 21 - March 19)
[[markata-go.theme_calendar.rules]]
name = "Winter"
start_date = "12-21"
end_date = "03-19"
palette = "winter-frost"

CLI Commands ¶ #

List all calendar rules:

markata-go theme calendar list

Output:

Theme Calendar Rules (3 configured)
============================================================

Christmas Season [ACTIVE]
  Date Range: 12-15 to 12-26
  Palette: christmas

Winter Frost
  Date Range: 12-01 to 02-28
  Palette: winter-frost

Halloween
  Date Range: 10-15 to 11-01
  Palette: spooky

Preview theme for a specific date:

# Check today's theme
markata-go theme calendar preview

# Check what theme applies on December 25
markata-go theme calendar preview 12-25

# Check New Year's Day
markata-go theme calendar preview 01-01

Output:

Checking theme for date: 12-25
----------------------------------------

Matching Rule: Christmas Season
Date Range: 12-15 to 12-26

Theme Overrides:
  Palette: christmas
  Font Family: Mountains of Christmas

Tips ¶ #

Order matters: Put more specific rules before general ones. Christmas should come before Winter.
Testing: Use markata-go theme calendar preview MM-DD to test any date without waiting for that day.
Smooth transitions: Consider overlapping date ranges with similar themes for gradual transitions.
Performance: Each rule is checked in order; keep the number of rules reasonable.
Combine with switcher: The calendar sets a default theme, but users can still override via the palette switcher if enabled.

Font Configuration ¶ #

markata-go provides flexible font configuration to customize your site’s typography without writing CSS.

Quick Start ¶ #

Add custom fonts via Google Fonts:

[markata-go.theme.font]
google_fonts = ["Inter", "Fira Code"]
family = "'Inter', sans-serif"
code_family = "'Fira Code', monospace"

Font Options ¶ #

Option	Description	Default
`family`	Body text font	System fonts
`heading_family`	Heading font (inherits from `family` if not set)	Same as `family`
`code_family`	Code/monospace font	System monospace
`size`	Base font size	`16px`
`line_height`	Base line height	`1.6`
`google_fonts`	Array of Google Fonts to load	`[]`
`custom_urls`	Array of custom font CSS URLs	`[]`

Using Google Fonts ¶ #

Specify fonts to load from Google Fonts:

[markata-go.theme.font]
# Load these fonts from Google Fonts
google_fonts = ["Inter", "Playfair Display", "JetBrains Mono"]

# Use them in your font families
family = "'Inter', sans-serif"
heading_family = "'Playfair Display', serif"
code_family = "'JetBrains Mono', monospace"

The google_fonts array automatically generates the Google Fonts CSS URL with weights 400, 500, 600, and 700.

Using Custom Fonts ¶ #

Load fonts from any URL:

[markata-go.theme.font]
custom_urls = [
  "https://fonts.example.com/my-font.css",
  "/fonts/local-font.css"
]
family = "'My Custom Font', sans-serif"

Typography Variables ¶ #

Font configuration generates CSS custom properties that you can use in your custom CSS:

Variable	Description
`--font-family`	Body text font stack
`--font-heading`	Heading font stack
`--font-code`	Code/monospace font stack
`--font-size`	Base font size
`--line-height`	Base line height

Complete Example ¶ #

[markata-go.theme]
palette = "catppuccin-mocha"

[markata-go.theme.font]
# Google Fonts to load
google_fonts = ["Source Sans Pro", "Source Serif Pro", "Source Code Pro"]

# Font assignments
family = "'Source Sans Pro', sans-serif"
heading_family = "'Source Serif Pro', serif"
code_family = "'Source Code Pro', monospace"

# Typography settings
size = "18px"
line_height = "1.7"

Using Self-Hosted Fonts ¶ #

For better performance and privacy, you can self-host fonts:

Download font files to static/fonts/
Create a CSS file defining @font-face rules
Reference it in custom_urls

/* static/fonts/fonts.css */
@font-face {
  font-family: 'MyFont';
  src: url('/fonts/MyFont-Regular.woff2') format('woff2');
  font-weight: 400;
}

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/MyFont-Bold.woff2') format('woff2');
  font-weight: 700;
}

[markata-go.theme.font]
custom_urls = ["/fonts/fonts.css"]
family = "'MyFont', sans-serif"

Best Practices ¶ #

1. Start with a Palette ¶ #

Don’t write CSS from scratch. Pick the closest palette and customize from there.

2. Use CSS Variables ¶ #

Override --color-* variables instead of hardcoding colors. This ensures consistency and makes future changes easier.

3. Keep Customizations Minimal ¶ #

The less you customize, the easier upgrades will be. Only override what you need.

4. Test Dark Mode ¶ #

If you customize colors, test both light and dark mode to ensure readability.

5. Check Accessibility ¶ #

Use markata-go palette check to verify your color choices meet WCAG guidelines.

Troubleshooting ¶ #

Styles Not Loading ¶ #

Check that CSS files exist in public/css/ after building
Verify your browser’s network tab shows CSS loading
Clear browser cache and rebuild: markata-go build

Custom CSS Not Applying ¶ #

Ensure custom_css path is relative to static/
Check for CSS specificity issues (theme styles may override yours)
Use browser dev tools to inspect applied styles

Template Not Found ¶ #

Verify the template file exists in templates/
Check the filename matches exactly (case-sensitive)
Ensure frontmatter template: value includes .html extension

Next Steps ¶ #

Now that you’ve styled your site, here are recommended next steps:

Customize your templates:

Templates Guide - Modify HTML structure, add custom partials, and use template inheritance

Organize your content:

Feeds Guide - Create filtered collections, archives, and tag pages

Deploy your site:

Deployment Guide - Deploy to GitHub Pages, Netlify, Vercel, or self-host

`j`	Scroll down
`k`	Scroll up
`g` `g`	Scroll to top
`Shift` `G`	Scroll to bottom
`d`	Half-page down
`u`	Half-page up

`j` / `↓`	Next post (in feeds)
`k` / `↑`	Previous post (in feeds)
`Enter` / `o`	Open highlighted post
`Shift` `O`	Open in new tab
`g` `h`	Go to home
`g` `s`	Focus search
`[`	Previous page
`]`	Next page
`s`	Toggle simple/rich feed view

`/`	Focus search input
`⌘CtrlK`	Focus search (alternative)
`y` `y`	Copy URL to clipboard
`?`	Show this help
`Esc`	Close / clear highlight

Themes, Palettes, and Aesthetics ¶

Quick Start ¶ #

Available Palettes ¶ #

Previewing Palettes ¶ #

Configuration Levels ¶ #

Level 1: Just Pick a Palette ¶ #

Level 2: Override Specific Colors ¶ #

Level 3: Add Custom CSS ¶ #

Level 4: Override Templates ¶ #

Theme Configuration Reference ¶ #

Available CSS Variables ¶ #

Article Reading Progress Indicator ¶ #

Dark Mode Support ¶ #

Using Different Palettes for Light/Dark ¶ #

Multi-Palette Theme Switcher ¶ #

Enabling the Switcher ¶ #

Keyboard Shortcuts ¶ #

Filtering Palettes ¶ #

Switcher Configuration Reference ¶ #

How It Works ¶ #

Styling the Switcher ¶ #

Hide on Mobile ¶ #

JavaScript API ¶ #

Event Handling ¶ #

Palette CLI Commands ¶ #

List All Palettes ¶ #

Get Palette Info ¶ #

Check Accessibility ¶ #

Export Palette ¶ #

Create New Palette ¶ #

Clone Existing Palette ¶ #

Fetch Palette from Lospec ¶ #

Pick Palette Interactively ¶ #

Creating Custom Palettes ¶ #

Aesthetics ¶ #

Quick Start ¶ #

Understanding the Separation ¶ #

Available Aesthetics ¶ #

Visual Comparison ¶ #

Configuration Examples ¶ #

Aesthetic Overrides Reference ¶ #

Aesthetic CLI Commands ¶ #

Creating Custom Aesthetics ¶ #

Keyboard Shortcuts ¶ #

Template Overrides ¶ #

Template Search Order ¶ #

Available Templates ¶ #

Example: Custom Footer ¶ #

Static Assets ¶ #

Per-Post Styling ¶ #

CSS Optimization ¶ #

How It Works ¶ #

Content Detection ¶ #

Benefits ¶ #

Custom CSS ¶ #

Media Borders and Gradient Effects ¶ #

Default Media Styling ¶ #

Configuring Media Borders ¶ #

Gradient Borders ¶ #

Available Gradient Presets ¶ #

Animated Gradient Borders ¶ #

Glow Effects ¶ #

Per-Image Styling ¶ #

CSS Variable Reference for Media ¶ #

Palette-Matching Gradients ¶ #

Custom Gradients ¶ #

Dark Mode Considerations ¶ #

Background Decorations ¶ #

Basic Configuration ¶ #

Multiple Layers ¶ #

Configuration Reference ¶ #

Tips for Background Decorations ¶ #

Example: Particle Background ¶ #

Seasonal Theme Calendar ¶ #

Basic Configuration ¶ #

How It Works ¶ #

Rule Configuration ¶ #

Rule Options Reference ¶ #

Background Overrides ¶ #

Font Overrides ¶ #