I have practiced Readme Driven Development on a number of my projects with varying milage. I have often found myself wishing for a few things:
- More structure When writing the documentation, and even more so when reading it. A single markdown file starts getting out of hand really quickly. On my presonal projects I go for org-mode, which keep me satisfied. But when working on a professional gig, it don't feel right to force other developers into org-mode/emacs.
- Prettiness Markdown is a quite reasonably readable format, but there is always room for prettyness.
Basically I wish for github-pages with more structure; so, a statically generate site.
To minimize the added complexity to our dev setup, and since I am already using docker to run dev-environments for almost all of my projects, I chose to leverage it for building my readme as a local "service". i.e I chose to structure my documentation with filesystem, and use docker to abstract the complexity of setting up the static site generator.
I have chosen hugo because of its simplicity. Its intuitive content management means near-zero learning curve for my teammates to start contributing documentation. I chose hugo-theme-learn because of its simplicity, mermaid.js support for UML diagrams, and well, prettiness.
I have a directory named
docs in our repository, with following
. ├── config.toml ├── content └── Dockerfile
Every markdown file in
content directory adds to the generated
Here is the Dockerfile I have used to create the docs container. It downloads and sets up hugo with the theme in a single command without anything other than docker installed on a developer's machine.
FROM alpine:latest WORKDIR /app EXPOSE 80 ENV HOST=0.0.0.0 RUN apk update && apk add hugo git ENV HUGO_THEME_URL='https://github.com/matcornic/hugo-theme-learn' ENV HUGO_THEME_COMMIT='2.4.0' RUN mkdir -p /themes/current \ && cd /themes/current \ && git init \ && git remote add origin $HUGO_THEME_URL \ && git fetch --depth 1 origin $HUGO_THEME_COMMIT \ && git checkout FETCH_HEAD \ && cd /app RUN echo "alias hugo='hugo --themesDir /themes --theme current'" > ~/.profile COPY . /app CMD hugo serve --port 3000 --bind='0.0.0.0' --themesDir /themes --theme current
When exposed on port
3000, it allows live-reloading of docs and search
in docs as well. It is possible to change the theme and theme version by
setting environment variables
when building the docker image.
config.toml file I've used for my
docs, which allow me to
configure the hugo theme with above mentioned environment variable only:
buildDrafts = true title = "My Project" # For search functionality [outputs] home = [ "HTML", "RSS", "JSON"] [params] author = "My team" description = "My project's cloud"