Quick Reference

A quick reference for common markata-go commands, configuration snippets, and troubleshooting tips.

Prerequisites #

Before using this guide, you should have:

  • markata-go installed ([Installation Guide](/docs/getting-started/#installation))
  • A basic understanding of TOML configuration format

CLI Commands #

Build and Serve #

# Build site
markata-go build

# Build with clean output directory
markata-go build --clean

# Build to custom output directory
markata-go build -o dist

# Start development server with live reload
markata-go serve

# Serve on custom port
markata-go serve -p 3000

# Serve with verbose output
markata-go serve -v

Content Creation #

# Create a new post
markata-go new "My Post Title"

# Create with specific template
markata-go new "Tutorial" -t tutorial

# Create in specific directory
markata-go new "About" --dir pages

# Create as published (not draft)
markata-go new "Announcement" --draft=false

# List available templates
markata-go new --list

Configuration #

# Initialize config file
markata-go config init

# Show resolved configuration
markata-go config show

# Show as JSON
markata-go config show --json

# Get specific value
markata-go config get output_dir
markata-go config get glob.patterns

# Validate configuration
markata-go config validate

Themes and Palettes #

# List available palettes
markata-go palette list

# Show palette details
markata-go palette info catppuccin-mocha

# Check accessibility
markata-go palette check catppuccin-mocha

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

# Clone a palette for customization
markata-go palette clone catppuccin-mocha --name "my-theme"

Configuration Snippets #

Minimal Site Config #

[markata-go]
title = "My Site"
url = "https://example.com"
output_dir = "public"

[markata-go.glob]
patterns = ["posts/**/*.md"]

Blog with RSS #

[markata-go]
title = "My Blog"
url = "https://myblog.com"
output_dir = "public"

[markata-go.glob]
patterns = ["posts/**/*.md", "pages/*.md"]

[[markata-go.feeds]]
slug = "blog"
title = "Blog"
filter = "published == True"
sort = "date"
reverse = true

[markata-go.feeds.formats]
html = true
rss = true
atom = true

Documentation Site #

[markata-go]
title = "Project Docs"
url = "https://docs.example.com"
output_dir = "site"

[markata-go.glob]
patterns = ["docs/**/*.md"]

[markata-go.markdown]
extensions = ["tables", "tasklist"]

[markata-go.components.doc_sidebar]
enabled = true
position = "right"
min_depth = 2
max_depth = 4

[search]
enabled = true
position = "navbar"

Custom Theme #

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

[markata-go.theme.variables]
"--color-primary" = "#8b5cf6"
"--content-width" = "800px"

[markata-go.components.nav]
enabled = true
position = "header"

[[markata-go.components.nav.items]]
label = "Home"
url = "/"

[[markata-go.components.nav.items]]
label = "Blog"
url = "/blog/"

[[markata-go.components.nav.items]]
label = "GitHub"
url = "https://github.com/user"
external = true

Frontmatter Snippets #

Basic Post #

---
title: "My Post"
date: 2026-01-24
published: true
tags:
  - topic
---

Full Post with Custom Fields #

---
title: "Complete Guide to X"
slug: "guide-to-x"
date: 2026-01-24
published: true
tags:
  - tutorial
  - guide
description: "A comprehensive guide covering everything about X."
template: "tutorial.html"

# Custom fields (available via post.Extra)
author: "Jane Doe"
reading_time: "10 min"
featured: true
series: "X Fundamentals"
series_order: 1
---

Draft Post #

---
title: "Work in Progress"
date: 2026-01-24
published: false
draft: true
---

Landing Page #

---
title: "Welcome"
slug: ""
published: true
template: "landing.html"
---

Filter Expressions #

Common filter expressions for feed configuration:

# Published posts only
filter = "published == True"

# Exclude drafts
filter = "published == True and draft == False"

# Posts with specific tag
filter = "'tutorial' in tags"

# Multiple tags (OR)
filter = "'python' in tags or 'go' in tags"

# Date range
filter = "date >= '2024-01-01' and date < '2025-01-01'"

# No future posts
filter = "published == True and date <= today"

# Featured posts
filter = "published == True and featured == True"

# By author (custom field)
filter = "author == 'Jane Doe'"

# Slug prefix (for sections)
filter = "slug.startswith('tutorials/')"

Template Snippets #

Date Formatting #

{{ post.Date|date_format:"January 2, 2006" }}
{{ post.Date|date_format:"2006-01-02" }}
{{ post.Date|rss_date }}
{{ post.Date|atom_date }}

Conditional Content #

{% if post.Tags %}
<ul class="tags">
  {% for tag in post.Tags %}
  <li><a href="/tags/{{ tag|slugify }}/">{{ tag }}</a></li>
  {% endfor %}
</ul>
{% endif %}

Custom Field Access #

{% if post.Extra.featured %}
<span class="badge">Featured</span>
{% endif %}

{% if post.Extra.author %}
<p>By {{ post.Extra.author }}</p>
{% endif %}

Pagination #

{% if page.HasPrev or page.HasNext %}
<nav class="pagination">
  {% if page.HasPrev %}
  <a href="{{ page.PrevURL }}">Previous</a>
  {% endif %}
  <span>Page {{ page.Number }}</span>
  {% if page.HasNext %}
  <a href="{{ page.NextURL }}">Next</a>
  {% endif %}
</nav>
{% endif %}

Environment Variables #

Override any config with MARKATA_GO_ prefix:

# Core settings
export MARKATA_GO_OUTPUT_DIR=dist
export MARKATA_GO_URL=https://example.com
export MARKATA_GO_TITLE="My Site"

# Build with overrides
MARKATA_GO_URL=https://staging.example.com markata-go build

Quick Troubleshooting #

Site Not Updating #

# Clean build
markata-go build --clean

# Clear browser cache or use incognito mode

Posts Not Appearing #

  1. Check frontmatter: published: true must be set
  2. Check filter: Ensure feed filter matches your posts
  3. Check date: Future dates won’t appear with date <= today filter
# Validate config
markata-go config validate

# Check resolved config
markata-go config show

RSS Feed Empty #

  1. Verify RSS is enabled in feed formats: 
    [markata-go.feeds.formats]
rss = true
  2. Check that posts match the feed filter
  3. Ensure url is set in config (required for absolute URLs)

Template Not Found #

  1. Check template path in frontmatter matches file name
  2. Verify file exists in templates/ directory
  3. Include .html extension: template: "custom.html"

Styles Not Loading #

  1. Check static/ directory contains CSS files
  2. Verify assets_dir setting if using custom location
  3. Check browser console for 404 errors

Build Fails #

# Verbose output for debugging
markata-go build -v

# Validate configuration first
markata-go config validate

Common File Locations #

Purpose Default Location
Configuration ./markata-go.toml
Content ./posts/**/*.md
Templates ./templates/
Static assets ./static/
Build output ./public/
Custom CSS ./static/custom.css

Next Steps #