Mark's Blog

This is my personal blog. It started out as a simple project to practice using htmx to make it an extremely lightweight and efficient website and tailwindcss for the styling.

One important requirement was that all my blog posts were to be written in markdown (in /content). It then turned out to be a bigger challenge to get the markdown file generation working than actually creating the blog. I first started out using pandoc to generate the markdown externally, but pandoc does some very weird styling and the syntax highlighting colors they support look really bad. I instead then opted for goldmark which is also in use by the hugo.

Installation

To get the blog running locally you first need go 1.21. You'll also need templ which has three quick ways to install:

go install github.com/a-h/templ/cmd/templ@latest # install via go
curl -o https://github.com/a-h/templ/releases/download/v0.2.432/templ_Linux_x86_64.tar.gz && chmod +x templ # install binary
nix run github:a-h/templ # run using nix

Once templ and go is set, you can generate the template go files and then start the server:

templ generate
go run .

Hot Reload

For the best developer experience I recommend getting air which enables hot-reloading on save. Install air and run it:

go install github.com/cosmtrek/air@latest
air

Styling

If you're working on the css or styling, it is recommended to also get the tailwindcss CLI tool and run it on the side to keep on updating the main.css stylesheet:

tailwindcss -i static/tw.css -o static/main.css --watch

Docker

It's also possible to start up the website using Docker:

docker compose up --build

This will build and start up the website as well as run the playwright tests. If you're building for arm64, you'll need to modify the Dockerfile and swap out the tailwindcss CLI tool installation for the arm64 version.

Testing

For extensive testing, Playwright is used. To make the install simpler, there's a Dockerfile in e2e/Dockerfile.playwright. Build and run it from the root directory.

docker build -t htmx-playwright -f e2e/Dockerfile.playwright .
docker run --rm -it --network host htmx-playwright /bin/bash

Nix

With the flake.nix and flake.lock files you can set up local development with the exact same dependency versions.

nix develop # downloads all required dependencies
nix build .#htmx-blog # build the blog
nix run .#htmx-blog # build and run the blog locally
nix run .#tailwindcss -- -i static/tw.css -o static/main.css --watch

Note: Tailwindcss still needs to be executed manually on the side to generate the static/main.css file

Creating Posts

Posts can be created by executing the post.sh script. Simply execute the following:

./post.sh content/posts/name_of_post