Creating a Digital Garden with Gitpod, GitLab, and mdzk

After reading How to Take Smart Notes by Sonke Ahrens, I wanted to adopt a better note-taking process. Tiago Forte encouraged me to build a second brain that I implemented with Notion. Recently, I found a system to process my thoughts into important notes or evergreen notes. Notion is great. I do not want to use it for storing important notes. I’ll share what led me to create a system to publish my digital garden.

Hugo

My website is a Hugo site that builds a statically generated website. All from markdown files and lets me deploy to AWS S3. That means I pay very little money to host files in a file storage system along with Route 53 DNS and Cloud Front as my CDN. AWS Certificate Manager allows me to create a wild star certificate for free to put HTTPS on my website and subdomains. Setup is a little tedious. Hugo is great if you enjoy customizing your site with golang templating. It’s powerful if you want to take the time to customize it. I want to embrace digital gardening to decrease the activation energy to write. Blog articles have too much ceremony to them that often deters writing. Hugo has powerful batteries included. Sometimes basic blog features like an Atom XML feed are not included. Instead of the valuable content you wanted to write, you end up learning the Atom specification and golang templating. Consistency and low friction enable a better writing and coding environment.

Code, Programs, Repositories, and Pipelines

I have a few old laptops that I am trying to find some new utility I can get out of them. For a time, I self-hosted my own GitLab. Configuration and maintenance are burdensome compared to using the cloud-hosted service. It is a real struggle to return to a codebase on a computer and remember if you have everything installed. Lately, I have been using Gitpod to host a scratch workspace not dependent on a particular computer I am running. The functionality is phenomenal! You can customize your environment and run nearly anything. I added this Gitpod configuration to make it simple to interactively write and view my blog post. If you work on .NET Core you cannot use Gitpod due to a booboo Google Kubernetes Engine made. Gitpod and GitLab pipelines streamline software development.

Decreasing the activation energy to share written ideas

It is easy to put the writing and publishing process on a pedestal. For many of us, the only way to get better is to write. Editing is a high leverage process that requires a lot of patience. If your ideas and content are valuable, readers will excuse poor verbose writing. No one is measuring your output. For most of us, we need to soundboard our ideas with someone verbally before we waste a lot of effort on a poorly thought-through idea. The purpose of a digital garden is to mature ideas over time and accept they might be raw and developing. We can also link ideas together to illuminate unforeseen connections and patterns.

Digital Gardens

On my search for digital garden software, there were a lot of options and ideas I saw others try. I considered staying with a combination of Hugo and Obsidian. One digital garden stood out for how nice it looked. I tried Quartz, for some reason, I could not get it to work with the way I’m using Obsidian and markdown files. I want to use wikilinks for connecting notes and not markdown links. I want to reduce the amount of configuration for note files because it is extra friction.

MDBook Zettlekasten - mdzk

I settled on a new project called mdzk. If you go to my digital garden you can see the mdbook theme this generates. The project appears to be in early development. I ran into some strangeness on Windows but managed to run it in Windows Subsystem for Linux fine. I almost abandoned it because it seemed to break on an obscure error. I discovered I needed to add backlinks-header = “Backlinks” to mdzk.toml along with the defaults from running mdzk init.

mdzk.toml

[mdzk]
authors = ["Alan Barr"]
ignore = ["obsidian.css", "publish.css", "zArchive"]
language = "en"
multilingual = false
src = "."
title = "Alan's Digital Garden"
backlinks-header = "Backlinks"

.gitlab-ci.yml

Here you can see the GitLab pipeline file I use to generate my digital garden.

---
stages:
    - install_build_mdzk
    - deploy

cache:
    paths:
    - html

install_mdzk:
    stage: install_build_mdzk
    image:
        name: curlimages/curl:latest
        entrypoint: [""]
    only:
        - main
    script:
        - curl -sL 'https://github.com/mdzk-rs/mdzk/releases/download/0.4.2/mdzk_0.4.2_x86_64-unknown-linux-musl.tar.gz' | tar -xz
        - ./mdzk build

deploy:
    image:
        name: golang:1.17.2-alpine3.13
        entrypoint: [""]
    stage: deploy
    only:
        - main
    script:
        - cd html/
        - go install github.com/bep/s3deploy/v2@latest
        - |-
            s3deploy -acl=public-read -bucket=notes.alanmbarr.com -distribution-id=SOMEID -max-delete=-1 -source=. -config=.s3deploy.yml -region=us-east-1            

The minor customization I added was using the s3deploy golang library to deploy my static site. The s3deploy library excels at transferring files for a static site because it compares ETags. The AWS CLI syncs everything, not only what changed. I did not find a simple way to specify gzipping files or setting headers. Hugo features the ability in its config syntax to define an s3 deployment. s3deploy follows a similar syntax for the .s3deploy.yaml.

.s3deploy.yaml

 routes:
    - route: "^.+\\.(js|css|svg|ttf)$"
      headers:
         Cache-Control: "max-age=31536000, no-transform, public"
      gzip: true
    - route: "^.+\\.(png|jpg)$"
      headers:
         Cache-Control: "max-age=31536000, no-transform, public"
      gzip: false
    - route: "^.+\\.(html|xml|json)$"
      gzip: true
    - route: "^sitemap\\.xml$"
      headers:
         Content-Type: "application/xml"
      gzip: true

Conclusion

The only way to get better at writing is to write. Sometimes that writing might be the first draft. It might even be foolish, thoughtless, low value, and selfish. We have the technology! We can rewrite and edit our writing anytime. People are not going to remember low-value content, so don’t sweat it. Make a digital garden to share ideas you are tending and nurturing into new valuable content. Learn in public. Share so that you’re improving and connecting new ideas. Who knows, maybe someone finds what you write and benefits from thoughts you wouldn’t publish without a digital garden.