Quick start

Each block below is the whole path for one platform: prerequisites, clone, config, first post, local preview. They end at the same place -- a site you can see at http://localhost:8000/ -- and from there, section 6 takes it to the internet.

./setup.sh is the config step: it asks for the settings a site needs, checks the answers as it goes, and writes config/site.yml and env.sh for you. Most questions can be skipped with Enter, which keeps what is there -- the ones that cannot are the site's title, short name, description, author and address for as long as they still hold the template's examples -- and nothing is written until you have seen the diff and confirmed it -- so it is also the way to change any of this later. If you would rather edit the files yourself, the numbered sections below are the full reference and section 2 still starts with the two cp commands; the wizard leaves both files commented and hand-editable either way.

macOS

The system Ruby is 2.6 from 2019 and Apple treats it as frozen, so the one real step is a current Ruby via Homebrew:

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
exec zsh
ruby -v    # 3.x now, not 2.6.10

(That PATH line is for Apple Silicon; on an Intel Mac it's /usr/local/opt/ruby/bin. brew install ruby prints the exact line for your machine at the end of its output -- trust that one.)

(No Homebrew yet? Install it first with the one command on brew.sh. git is already there on any Mac with the Xcode Command Line Tools -- macOS offers to install them the first time you type git.)

Then:

git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

The system nano is as old as the system Ruby -- if the editor step complains about options, set your own: export EDITOR=vim (or code -w, or plain nano).

An icon instead of cd myblog && ./blog.sh. On a Mac ./setup.sh ends by offering to put a launcher in Applications: an icon, named after the site and wearing its favicon, that opens Terminal in the site's folder and runs ./blog.sh. It is nothing more than that -- no window of its own, nothing blog.sh does not do -- and the answer to Enter is no, since a yes puts something outside this folder. ./setup.sh --launcher makes it at any later time, and makes it again for a site whose folder moved: the folder is written into the launcher, so one site has one launcher -- under one name. The launcher is called what the site is called: after a change of site.short_name the next --launcher makes one under the new name, and the old one stays where it was until it is dragged to the Trash.

Three things to know about it, all of them macOS's:

• The first double-click asks whether the launcher may control Terminal, and under the question stands one sentence, in the site's language, saying what the launcher does. Allow it. Refused, the icon does nothing, and the question is not asked again -- the switch is then in System Settings → Privacy & Security → Automation.
• blog.sh runs in the window Terminal opens as it starts, or in a new one when Terminal was already running. Either way Terminal keeps the window open after blog.sh ends, saying the process completed. Whether it closes instead is Terminal's own setting: Settings → Profiles → Shell → "When the shell exits".
• It lands in /Applications, or in ~/Applications for an account that may not write there. An application of the same name that blog.sh did not make is never replaced, and neither is the launcher of ANOTHER site called the same -- two sites nobody has named yet are both "blog.sh"; give one a site.short_name of its own. BLOG_SH_LAUNCHER_DIR=<folder> puts the launcher somewhere else.

Linux (Debian/Ubuntu shown; any distro works)

sudo apt update && sudo apt install -y ruby-full git

(ruby-full rather than the bare ruby -- see the default-gems note below. On Fedora: sudo dnf install ruby; on Arch: sudo pacman -S ruby -- both already complete.)

git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

Windows

blog.sh's wrappers are bash, so on Windows it runs inside WSL2 -- Microsoft's Linux environment, one command to set up. In PowerShell as Administrator:

wsl --install

Reboot when asked; Ubuntu opens and asks you to pick a username. From that Ubuntu terminal, it's the Linux path verbatim:

sudo apt update && sudo apt install -y ruby-full git
git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

Two Windows-specific notes: clone into the Linux home (~/myblog, as above), not /mnt/c/... -- file permissions (chmod 600 on your tokens) and speed only work properly on the Linux side; and http://localhost:8000/ works straight from your Windows browser, WSL2 forwards it. Git Bash instead of WSL2 mostly runs too, but the interactive menus degrade (mintty isn't a TTY to a native Ruby), non-ASCII output is garbled until the console is switched to UTF-8 (chcp 65001), and chmod protects nothing on NTFS -- with real tokens in env.sh, WSL2 is the supported route.

The engine has no build-time network dependencies: a machine with Ruby and bash can build the whole site offline.

On "no gems" and default gems. Everything in blog.sh is written against Ruby's core standard library -- nothing to gem install, ever, for the engine itself to run. The one nuance: the optional Pixelfed/RSS sidebar widgets parse XML with rexml, which Ruby ships as a default gem -- bundled with a normal ruby install, but some Linux distributions split their Ruby package and leave default gems out of the minimal one. Importing is not optional about it: every XML source reads through rexml, which is WordPress, Blogger, Squarespace, podcasts, any RSS or Atom feed, the Wayback rescue and LiveJournal. If none of that is in your way -- no XML import, no widgets.pixelfed/widgets.rss -- it never comes up; if it is, and you see a LoadError about rexml, either gem install rexml or install your distro's fuller Ruby package -- e.g. ruby-full instead of the bare ruby on Debian/Ubuntu (Arch's own ruby package already includes the full standard library, no separate install needed there). ./blog.sh preview, by contrast, needed no such caveat to begin with: it's a small built-in static server (lib/preview_server.rb), not the webrick-dependent ruby -run -e httpd one-liner some other guides suggest.