README
¶
MarkGo
A blog engine where you write first and categorize never.
Type two sentences without a title and it becomes a thought. Paste a URL with commentary and it becomes a link. Write something long with a title and it becomes an article. Ask a question and it becomes an AMA. Plus a fifth type — page — for evergreen content (explicit type: page in frontmatter, served at /p/<slug>, listed at /p). Four inferred, one explicit. No database. No build step.
Quick Start
git clone https://github.com/1mb-dev/markgo && cd markgo
make build
./build/markgo init --quick
./build/markgo serve
# Visit http://localhost:3000
Or download a release from GitHub Releases.
Live Install
log.1mb.dev — running latest release (may briefly lag during binary-pull cycles).
What You Get
Write from anywhere — CLI for drafting in your editor, web compose form for publishing from your phone. Quick capture: tap the FAB, type a thought, hit Publish. Under 5 seconds.
SPA navigation — Instant page transitions. The router fetches HTML and swaps content — no full page reloads, no client-side rendering framework.
Works offline — Installable PWA with Service Worker. Pages cached for offline reading. Compose queue syncs when you're back online.
Mobile-native feel — Bottom navigation, full-screen search overlay, visual viewport handling for iOS keyboards. CSS starts at 320px and works up.
Your files, your control — Articles are markdown files with YAML frontmatter. Edit in vim, version with git, back up however you like. The compose form writes files to disk — it's a convenience layer, not a lock-in.
Zero dependencies — Single Go binary with embedded web assets. No Node.js, no PHP, no database. markgo init creates only your content directory and config.
Usage
markgo serve # Start the web server
markgo init [--quick] # Initialize a new blog
markgo new [--title "..." --tags "..."] # Create an article
markgo new --type thought # Quick thought (no title needed)
markgo new --type link # Share a link
markgo new --type ama --title "Why X?" # AMA question (admin moderated)
Configuration
Copy .env.example to .env:
BLOG_TITLE="Your Blog Title"
BLOG_AUTHOR="Your Name"
BASE_URL="https://yourdomain.com"
Admin credentials enable the compose form, admin panel, and login:
ADMIN_USERNAME=you
ADMIN_PASSWORD=something-strong
See Configuration Guide for all options.
Deploy
Docker:
docker compose up -d
See Deployment Guide for systemd, reverse proxy, and production setup.
Development
make dev # Dev server with hot reload
make build # Build binary
make lint # golangci-lint
make test # Run tests
make test-race # Race detector
make coverage # Coverage report
Documentation
- Getting Started — Install, first post, and features overview
- Configuration — All environment variables
- Architecture — How the system works
- API — Every HTTP endpoint
- Deployment — Docker, systemd, reverse proxy
- Design Language — The principles behind every decision
License
MIT License — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
markgo
command
Package main provides the unified CLI entry point for all MarkGo commands.
|
Package main provides the unified CLI entry point for all MarkGo commands. |
|
internal
|
|
|
commands/init
Package init provides the blog initialization command for MarkGo.
|
Package init provides the blog initialization command for MarkGo. |
|
commands/new
Package new provides the article creation command for MarkGo.
|
Package new provides the article creation command for MarkGo. |
|
commands/serve
Package serve provides the HTTP server command for the MarkGo blog platform.
|
Package serve provides the HTTP server command for the MarkGo blog platform. |
|
config
Package config provides configuration management for MarkGo blog engine.
|
Package config provides configuration management for MarkGo blog engine. |
|
constants
Package constants provides application-wide constants for the MarkGo blog engine.
|
Package constants provides application-wide constants for the MarkGo blog engine. |
|
errors
Package errors provides custom error types and error handling utilities for the MarkGo blog engine.
|
Package errors provides custom error types and error handling utilities for the MarkGo blog engine. |
|
etag
Package etag provides HTTP entity-tag generation and If-None-Match comparison, shared by the HTML render path (weak, body-derived validator) and static-asset serving (strong, build-version-derived validator).
|
Package etag provides HTTP entity-tag generation and If-None-Match comparison, shared by the HTML render path (weak, body-derived validator) and static-asset serving (strong, build-version-derived validator). |
|
handlers
Package handlers provides HTTP request handlers for the MarkGo blog engine.
|
Package handlers provides HTTP request handlers for the MarkGo blog engine. |
|
middleware
Package middleware provides HTTP middleware for the MarkGo blog engine.
|
Package middleware provides HTTP middleware for the MarkGo blog engine. |
|
models
Package models defines data structures and models for the MarkGo blog engine.
|
Package models defines data structures and models for the MarkGo blog engine. |
|
services
Package services provides business logic layer for MarkGo blog engine.
|
Package services provides business logic layer for MarkGo blog engine. |
|
services/article
Package article provides article management services for the MarkGo blog engine.
|
Package article provides article management services for the MarkGo blog engine. |
|
services/seo
Package seo provides SEO functionality including meta tags, schema markup, and sitemap generation.
|
Package seo provides SEO functionality including meta tags, schema markup, and sitemap generation. |
|
slug
Package slug provides canonical slug generation and path-containment primitives shared by the article repository and the compose service.
|
Package slug provides canonical slug generation and path-containment primitives shared by the article repository and the compose service. |
|
Package web embeds templates and static assets into the binary.
|
Package web embeds templates and static assets into the binary. |