Guides Hub
Welcome to the markata-go documentation! Choose a learning path based on your goals, or browse individual guides below.
The Icon Shortcodes guide and Markdown Containers show how to build responsive icon cards, feature rows and architecture diagrams entirely in Markdown. Coding agents can follow the bundled Markata skill for these patterns.
Learning Paths
Beginner Path
Time: ~30 minutes | Get your first site running
Perfect if you're new to markata-go or static site generators in general.
| Step | Guide | Time | Description |
|---|---|---|---|
| 1 | Getting Started | 10 min | Installation and first site |
| 2 | Quickstart | 5 min | Build and serve your site |
| 3 | Frontmatter | 10 min | Understanding post metadata |
| 4 | Markdown Features | 5 min | Writing content with Markdown |
After completing: You'll have a working site with your first posts.
Blogger Path
Time: ~45 minutes | Create a polished blog
For writers and content creators who want a beautiful, functional blog.
| Step | Guide | Time | Description |
|---|---|---|---|
| 1 | Getting Started | 10 min | Installation and setup |
| 2 | Themes and Styling | 10 min | Customize your site's look |
| 3 | Feeds | 10 min | RSS, archives, and tag pages |
| 4 | Syndication Feeds | 5 min | RSS/Atom configuration |
| 5 | Deployment | 10 min | Go live on GitHub Pages, Netlify, etc. |
After completing: You'll have a deployed blog with RSS feeds and custom styling.
Documentation Site Path
Time: ~1 hour | Build a documentation site
For teams and projects that need structured documentation.
| Step | Guide | Time | Description |
|---|---|---|---|
| 1 | Getting Started | 10 min | Installation and setup |
| 2 | Configuration | 15 min | Site-wide settings |
| 3 | Sidebars | 10 min | Navigation sidebars |
| 4 | Templates | 15 min | Custom layouts |
| 5 | Search | 10 min | Add site search |
After completing: You'll have a documentation site with navigation, search, and custom templates.
Developer Path
Time: ~2 hours | Master markata-go
For developers who want full control and customization.
| Step | Guide | Time | Description |
|---|---|---|---|
| 1 | Getting Started | 10 min | Installation and setup |
| 2 | Configuration | 15 min | Complete config reference |
| 3 | Templates | 20 min | Template system and filters |
| 4 | Feeds | 15 min | Advanced feed configuration |
| 5 | Plugin Development | 30 min | Create custom plugins |
| 6 | Dynamic Content | 15 min | Jinja expressions in content |
| 7 | Deployment | 15 min | CI/CD and self-hosting |
After completing: You'll understand the full architecture and can extend markata-go for any use case.
All Guides by Topic
Getting Started
- Getting Started - Complete installation and first site tutorial
- Quickstart - 5-minute quick start
- Quick Reference - Common commands and snippets
Content Creation
- Frontmatter - Post metadata and custom fields
- Markdown Features - Tables, code blocks, admonitions, wikilinks
- Image Library - Search and reuse site images
- Web Awesome Components - Image comparisons and raw Web Awesome components
- Post Formats - HTML, Markdown, and OG card outputs
Configuration
- Configuration - Complete configuration reference
- Feeds - Creating filtered, sorted, paginated collections
- Syndication Feeds - RSS, Atom, and JSON feed setup
Appearance
- Themes and Styling - Color palettes, CSS variables, custom styles
- Templates - Pongo2/Jinja2 template customization
- Sidebars - Table of contents and feed navigation
Features
- Search - Pagefind integration for site search
- Content Diagnostics - Inspect build dispositions and reason codes
- View Transitions - Smooth page navigation animations
- Resource Hints - Auto-generate dns-prefetch and preconnect
- YouTube Embeds - Embedding YouTube videos
- Web Awesome Components - Image comparisons with CDN or vendored assets
- Dynamic Content - Jinja expressions in Markdown
- Structured Data - JSON-LD and SEO
Deployment
- Deployment - GitHub Pages, Netlify, Vercel, Docker
- Self-Hosting - nginx, Caddy, and manual deployment
- Nginx-native Redirects - Generate and safely deploy
redirects.confwith HTML fallbacks
Advanced
- Agent Skills - Install the bundled markata-go site skill for coding agents
- Plugin Development - Creating custom plugins
- Static SVG Foundation - Developer-only backend SVG contract and adapter roadmap
- Migration - Migrating from other static site generators
- Performance and Profiling - Benchmarking and profiling builds
- Resource Hints Implementation - Technical details
Quick Links
| Task | Guide |
|---|---|
| Install markata-go | Getting Started |
| Change site colors | Themes |
| Add RSS feed | Syndication Feeds |
| Fix excessive dns-prefetch | Resource Hints Quick Fix |
| Deploy to GitHub Pages | Deployment |
| Configure nginx redirects | Nginx-native Redirects |
| Create a custom template | Templates |
| Install the agent skill | Agent Skills |
| Filter posts by tag | Feeds |
Need Help?
- Troubleshooting - Common issues and solutions
- Quick Reference - Common commands and config snippets
- GitHub Issues - Report bugs or request features