This is a straightforward post.
It's a brief walkthrough of what Clio offers today, based on how I've been building and using it. No frills, just a clear look at the tool and its surface area.
I wanted a tool I could use every day. Something built around text and Markdown, editable locally without needing an internet connection, but trivial to publish when ready. Static output, fast by nature, easy to host anywhere. Clio grew out of that need.
What it is
Clio is a static site generator with a built-in dashboard. You write in Markdown, manage content through a local web interface, and generate plain HTML that can be served anywhere static files are supported.
Most generators expect you to work with configuration files and folder structures. Clio takes a different approach: tags, sections, templates, contributors, and settings are all managed through the browser. While you work, content lives in a single SQLite file with automatic backups. When you publish, the output is plain HTML with no runtime dependencies.
It runs as a single binary with no external services, no asset pipeline, and no required configuration. For portability, Markdown export produces a clean file tree with frontmatter and images. Publishing is one click; git operations happen behind the scenes.
Sections
Sites in Clio are built from sections. Each section defines its own path, layout, and rules, allowing you to organize a blog, a portfolio, notes, or standalone pages as separate spaces under the same site.
Sections can share templates and cross-reference each other, or remain fully isolated. Some behave like independent minisites; others feel closer to newspaper sections, where connections across content matter.
Navigation blocks and related content are configurable: scoped per section or site-wide, enabled or disabled depending on the structure you want.
Content
Clio covers the essentials: drafts, scheduled publication, tags, summaries, featured flags, and SEO metadata. Content can be grouped into series with automatic navigation, and authors are attributed explicitly with generated archive pages.
Tags can be global or scoped to a section. Related content can stay local or cross section boundaries. Defaults are sensible; configuration is optional.
Images live alongside content, carry metadata, and are rewritten during generation so the published site is fully self-contained.
The editor
The editor offers optional live preview, automatic saving, and a focus mode for distraction-free writing. You can insert images, format text, and add links, but the goal is not to replace your editor. It's to stay close to the text.
Preview is instant. Clio runs a local server that regenerates pages on demand, so refreshing the browser is enough to see changes. Publishing means generating static HTML and pushing to a git repository. Once published, your site is just files.
Contributors
Clio is designed primarily for a single editor, though multiple users can share the same workspace. Collaboration is not the focus.
Separately, Clio supports contributors: authors displayed on the site with their bio, photo, and social links. Guest posts don't require dashboard access, and content can be published under one or multiple names.
Proofread
Clio includes an AI-powered proofreading tool accessible from the content editor. It reviews grammar, style, repeated phrases, and overused expressions in a single pass.
Select text or proofread the entire document. The tool returns a summary, a corrected version, and a detailed list of changes with explanations. You can apply corrections with one click or review them individually before deciding.
It detects the language of your text automatically and respects quoted material. The goal is to preserve your voice while catching mistakes that are easy to miss.
Embeds
Clio supports embedding videos and audio from external platforms directly in your Markdown. YouTube, Vimeo, TikTok, and SoundCloud are supported through a simple fenced code block syntax that keeps your content readable.
You specify the provider and the video or track ID. Clio handles the rest: responsive containers, lazy loading, aspect ratio adjustments for vertical video, and accessible iframe attributes. No raw HTML required.
For platforms not covered by the built-in providers, you can embed raw HTML directly in your Markdown. This gives you support for any service that offers an embed code.
While editing, embeds appear as labeled placeholders so the editor stays fast. The actual players render in the generated site.
Scheduled Publishing
Content can have a future publication date. When that date arrives, Clio regenerates the site and pushes it to git. Until then, the content is excluded from index pages, feeds, and the generated output entirely.
This means you can write several posts in one sitting, assign each a different date, and not think about it again. Nothing goes live before its time.
A background scheduler checks for pending content at a configurable interval. Manual publishing still works independently, and both can be used together.
Backup and Restore
Clio can export your entire site to a portable format: Markdown files with YAML frontmatter, layout templates, contributor profiles, images, and all associated metadata. The backup is pushed to a Git repository, giving you a versioned history of your content.
Restoring works in reverse. Point a new Clio instance to a backup directory and it recreates sections, tags, contributors, layouts, and content with all relationships intact. If the backup comes from plain Markdown without Clio metadata, it falls back to a basic import that resolves what it can from frontmatter and creates the rest automatically.
The result is full portability: migrate between servers, maintain offline backups, or spin up a fresh instance from an exported repository.
Import
You can write in whatever editor you prefer. Clio watches a directory for Markdown files and syncs them into your site. Files stay where they are; Clio tracks them by path and detects changes on each import cycle.
YAML frontmatter is parsed automatically: title, slug, author, tags, and metadata. If a file changes externally while you've also edited it through the dashboard, Clio flags the conflict instead of overwriting silently.
Details on directory setup and conflict resolution are in the import guide.
Site integrations
A generated Clio site works out of the box with no extras required. But if you need analytics, search, or SEO controls, a few integrations are available directly from settings.
Google Analytics is enabled by adding your tracking tag. Google Search adds a localized search widget scoped to your site. A cookie consent banner can be toggled on with configurable text and behavior. And robots.txt is generated automatically with sensible defaults, editable if you need finer control.
Each one is optional, independent, and configured from the dashboard. The userguide covers analytics, search, cookie banner, and robots.txt.
Contact Forms
You define a form in Markdown using a fenced block syntax, or insert one from the editor toolbar the same way you would an embed. When the site is generated, Clio produces a working HTML form. Submissions arrive in the dashboard, where you can review and manage them.
Spam protection includes a honeypot field and rate limiting. No external service required. The form works whether you serve the site through Cloudflare Tunnel or host it on GitHub Pages.
This is early stage. The results are promising, but I wouldn't call it production-ready yet. The architecture behind it, handling form submissions on a static site without an external backend, is an interesting problem that probably deserves its own post at some point.
Syntax and configuration details are in the forms guide.
REST API
Clio exposes a REST API for managing content programmatically. Token-based authentication, CRUD operations on posts, and commands for publish, generate, and backup are all available. The first phase is complete; more endpoints will follow to cover images, tags, layouts, contributors, and settings.
A practical example: you can publish directly from Neovim with a keymap that calls the API. Write in your terminal, hit a shortcut, and the site rebuilds and deploys without touching the browser.
Designing a local API for a CMS, token auth, editor integration, is a topic with enough surface area for its own post. For now, the API guide covers authentication, available endpoints, and usage examples.
Self-hosting with Docker
Clio provides a Docker image and a docker-compose setup that includes Cloudflare Tunnel integration. You can run it with a quick tunnel for testing or configure a named tunnel for a more permanent setup.
The architecture separates two servers: the dashboard stays local and private, while a preview server is exposed through the tunnel. Your admin interface is never public.
Like contact forms, this is functional but not production-ready. The basic flow is solid, but the more involved tunnel configurations still need testing in a sandboxed environment, away from anything my local setup might be papering over. Self-hosting with tunneling, the two-server architecture, and the tradeoffs involved are worth exploring in a dedicated post.
Setup instructions and configuration options are in the Docker guide.
What's next
Everything described here was part of the original idea. The pieces are in place. There are still ergonomics to revisit and details to get right, but the scope I had in mind when I started is what exists now.
Most static site generators are designed to be general-purpose, and that flexibility comes at a cost. Getting a blog or a section-based site running often means dealing with directory conventions, template logic, and configuration that exist to support use cases you don't have. Clio is opinionated about what it does, and that's by design. Publishing, backups, image management with metadata and attribution, forms, these are things I want solved and always available, not assembled from scratch each time.
The road ahead is refinement: better test coverage, edge cases, progressive improvement. Not more features. Just making what's there more solid, at a steady pace. Some of the screenshots in the gallery and on the site are slightly behind the current version. The interface has evolved since they were taken.
Features
Core workflow
- Markdown editor
Live preview as you type, including images. Or hide the preview and write in plain Markdown. - Zen mode
Distraction-free writing. Dark mode available. Quick toggle via buttons or shortcuts. - Autosave
Changes persist automatically. No manual save, no lost work. - Git-based publishing
Generate static HTML, push to any repository. Deploy anywhere.
Content model
- Sections
Each section can have its own layout for both the index and the article view. All layouts are editable from the interface. - Series
Group related posts with automatic navigation between parts. Generation of series content still needs some work. - Drafts and scheduling
Mark content as draft, or set a future publication date. Either way, it stays hidden until ready. - Tags
Site-wide tags with automatic archive pages. Related content blocks can connect within a section or across the site, configurable in settings. - Related content
Cross-reference within or across sections.
Images and assets
- Image management
Images section to edit alt text and titles globally. Images can be reused across posts by path. - Automatic path rewriting
References update during generation. Output is self-contained. - Header and inline support
Use images as post headers or embed them in content.
Templates and customization
- Go templates
Simple, fast, no build step. Full control over HTML output. - Default layouts included
Start immediately. Customize later if needed. - Section-level overrides
Different sections can look completely different.
Import
- External Markdown files
Import Markdown files from a watched directory. Files remain in place and are tracked for changes. - Frontmatter support
Title, slug, author, tags, and metadata are parsed automatically from YAML frontmatter. - Change detection
Modified files are flagged for reimport. Conflicts between local edits and web changes are detected and surfaced.
Analytics and search
- Google Analytics
Add your tracking tag in settings. Support for other providers via custom snippets is planned. - Site search
Google Search widget for localized search within your site. - Cookie banner
Configurable consent banner with customizable text and behavior. Toggle on from settings. - Robots.txt
Generated automatically with sensible defaults. Editable for finer control. - Sitemap
Generated automatically on each build.
Multi-site
- Multiple independent sites
Manage several unrelated sites from the same Clio installation, each with its own content, settings, and workspace.
Portability
- Markdown export
Full export with YAML frontmatter including all metadata, sections, and tags. Assets correctly referenced. The export tree mirrors the published structure. - Version control friendly
Track content in git independently from the generator. - No lock-in
Your content is always yours, in a format any tool can read.
Technical details
- Single binary
Download and run. No installation, no dependencies. A Docker image with Cloudflare Tunnel integration is also available for self-hosting. - No external services
Everything runs locally. No accounts, no API keys. - SQLite storage
Content lives in a single database file. Easy to back up, easy to move. PostgreSQL might follow. - Cross-platform
Runs on Linux, macOS, and Windows.
Scheduled publishing
- Future dates
Set a publication date in the future. The content stays hidden until that date arrives. - Background scheduler
Clio checks for pending content at a configurable interval and publishes automatically. - Visibility rules
Drafts never publish. Non-draft content with a future date is excluded from generation entirely - no index pages, no feeds, no output - until the scheduled time passes. - Flexible intervals
Check every 5 minutes or every 2 hours. Go duration format: 5m, 15m, 30m, 1h, 2h. - Works with manual publish
Manual and scheduled publishing coexist. The scheduler tracks the last publish timestamp to avoid redundant work.
Interaction
- Contact forms
Define forms in Markdown. Submissions arrive in the dashboard. Honeypot and rate limiting included. - REST API
Token-based authentication. CRUD on posts, publish, generate, and backup endpoints. First phase complete.
Deployment
- Docker
Docker image and docker-compose with Cloudflare Tunnel integration. Quick tunnels for testing, named tunnels for permanent setups. - Cloudflare Tunnel
Expose your preview server publicly while keeping the dashboard private and local.
Roadmap
- API: next phases
Endpoints for images, tags, layouts, contributors, and settings.
References: