Guide

Everything you need to go from a fresh install to publishing posts regularly, including the SSH remote workflow.

The slug

When you run writer my-post, the part after writer is the slug. It becomes the URL path for your post (yourdomain.com/posts/my-post/), so keep it clean:

All lowercase: my-post, not My-Post
Hyphens for spaces: on-the-road, not on the road
Letters, numbers, hyphens only: no underscores, dots, or special characters

writer on-the-meaning-of-home
writer coffee-and-clarity
writer 2026-reflections

The full workflow

Run writer my-slug: writer checks your config and dependencies, then asks for a title.
Title (required): type your post title and press Enter. If you leave it blank, writer asks once more, then exits.
Tags (optional): comma-separated. Press Enter to skip. Leading/trailing whitespace is trimmed. Empty entries (e.g. double commas) are silently dropped.
Editor: your editor launches with the cursor on the first blank line below the frontmatter. Write your post. Save and close.
Description (optional): a one-line summary added to frontmatter. Press Enter to skip.
Confirm: press Enter or Y to build and push. Press N to save the file without publishing.

Saving a draft

writer my-post --draft

Sets draft: true in frontmatter. Hugo skips draft posts in production builds. Useful for posts you want to write now and publish later.

Building without pushing

writer my-post --no-push    # build the site, but skip git push
writer my-post --no-build   # skip build; only commit and push the file

Previewing frontmatter (dry run)

writer my-post --dry-run

Prints the frontmatter that would be written, then exits. No files are created or modified. Useful for checking the output format.

---
title: "My Post"
date: 2026-05-23T07:00:00-06:00
slug: "my-post"
draft: false
---

Choosing an editor

The default editor is micro: a small terminal editor that behaves like a normal editor: Ctrl+S saves, Ctrl+Q quits. No modes, no configuration needed, Markdown syntax highlighting built in.

To install micro on Linux:

curl https://getmic.ro | bash
mv micro ~/.local/bin/micro

To switch to a different editor, run writer --setup and update the EDITOR prompt, or edit ~/.config/writer/config directly:

EDITOR=nano    # or vim, nvim, hx, emacs — any terminal editor

Using writer over SSH

The intended use case for writer is a remote server: you SSH in, run one command, write, and the post is live. No Hugo, git, or editor needed on your laptop.

ssh you@yourserver.com
writer my-post

Set SITE_DIR in your config (via writer --setup) to point to your Hugo project directory on the server. Writer will cd there automatically before doing anything, so you don't need to be in the right directory when you SSH in.

SITE_DIR=/var/www/your-site

One-command access from your laptop

# ~/.bashrc or ~/.zshrc on your laptop
alias blog='ssh you@yourserver.com'

Then blog drops you straight into the server and you are one writer command away from a published post.

Unreliable connections (mobile, etc.)

Run writer inside tmux so a dropped connection doesn't interrupt a write in progress:

tmux new-session -A -s write
writer my-post

If you disconnect, tmux attach on reconnect puts you back where you were.

Setting up git auth on the server

The server needs to push to your git remote without a password prompt. The recommended way is an SSH deploy key:

# On the server — generate a deploy key
ssh-keygen -t ed25519 -C "yourserver-writer" -f ~/.ssh/writer_deploy

# Print the public key and add it to GitHub/Codeberg with write access
cat ~/.ssh/writer_deploy.pub

# ~/.ssh/config on the server
Host github.com
    IdentityFile ~/.ssh/writer_deploy
    IdentitiesOnly yes

# Test it
ssh -T git@github.com

Full server architecture

[Your laptop]
     │
     │  ssh you@yourserver.com
     ▼
[Remote server]
  ├── /var/www/your-site/        ← Hugo project (git repo)
  ├── ~/.local/bin/writer        ← writer script
  ├── ~/.config/writer/config    ← writer config
  └── micro, hugo, git           ← all dependencies live here
          │
          │  git push
          ▼
[GitHub / Codeberg / Gitea]
          │
          │  webhook or CI/CD (optional)
          ▼
     [Live site]

Project-local config (`.writerrc`)

Place a .writerrc file in the root of your Hugo site to override global settings for that project only. Settings here take precedence over ~/.config/writer/config.

# .writerrc — project-local overrides
DEFAULT_SECTION=notes
FRONTMATTER_FORMAT=toml
GIT_COMMIT_MSG=post: {slug}

Useful if you manage more than one blog, or want a specific section or frontmatter format for one project without changing your global defaults.

Re-running setup

writer --setup

Every setting is shown with its current saved value. Press Enter to keep it, or type a new value. Your config is saved when you finish the wizard.

Reference → ← Home