12-29-2020: Lab Notebook Setup

Introduction

I’ve noticed a few people whom I follow and admire online have started to keep lab notebooks. I first ran across the idea when I saw @whitequark’s notebook lab.whitequark.org, and then this evening I ran across @bitshiftmask’s lab.jamesmunns.com by chance and saw they were doing a similar thing with mdbook which seems very easy to use and straight forward to setup and maintain.

I’ve been on a personal knowledge management kick recently, and I’ve been playing whit obsidian.md for maintaining a ‘second brain’. The idea of a public lab notebook seems like an interesting idea that I want to play with. So this first post is going to be the process of setting this up.

Boot Strapping The Book

To get started with the notebook first I created a new GitHub repository github.com/bgianfo/lab-notebook. Then I configured my lab notebook mdbook project just enough so that this page building.

C:\src\lab-notebook>tree /A /F
|   .gitignore
|   book.toml
|   README.md
|
\---src
    |   SUMMARY.md
    |
    \---notes
            2020-12-29.md

Once we have the shell of the project setup and can use mdbook serve to have the system automatically rebuild and refresh pages as we edit them:

C:\src\lab-notebook>mdbook serve
2020-12-29 03:02:15 [INFO] (mdbook::book): Book building has started
2020-12-29 03:02:15 [INFO] (mdbook::book): Running the html backend
2020-12-29 03:02:15 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
2020-12-29 03:02:15 [INFO] (warp::server): Server::run; addr=[::1]:3000
2020-12-29 03:02:15 [INFO] (warp::server): listening on http://[::1]:3000
2020-12-29 03:02:15 [INFO] (mdbook::cmd::watch): Listening for changes...
2020-12-29 03:02:22 [INFO] (mdbook::cmd::serve): Files changed: ["notes\2020-12-29.md"]
2020-12-29 03:02:22 [INFO] (mdbook::cmd::serve): Building book...
2020-12-29 03:02:22 [INFO] (mdbook::book): Book building has started
2020-12-29 03:02:22 [INFO] (mdbook::book): Running the html backend

Publishing

Now that we have the basics of the book building, I want to get the notebook published, and served off of my subdomain lab.bjg.io where nothing currently resides today. To make this as pain free as possible I was hoping to use github pages for this, the same as the rest of my site. When poking around I found the mdbook-action which allows you to painlessly publish your mdbook from a github actions workflow.

Following the documentation I was able to create a simple workflow (324781fae):

name: Publish To GitHub Pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

I looked for signs that the action ran, and nothing… so double checking the pipeline I realized that GitHub created the new default branch as main, not master. So our pipeline wasn’t running because we are listening for push events on the wrong branch. Announcement: https://github.com/github/renaming

So we need one small change to our pipeline to fix things up:

commit 78fd8a787cf6a2f49eca8e402eb6aede9caad174
Author: Brian Gianforcaro <b.gianfo@gmail.com>
Date:   Tue Dec 29 03:17:52 2020 -0800

    CI: Fix to modern branch name

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index cf0fa96..7707376 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -3,7 +3,7 @@ name: Publish To GitHub Pages
 on:
   push:
     branches:
-      - master
+      - main

That worked and automatically created a new gh-pages branch in the repository. In the GitHub repository settings I was then able to configure github pages to use the new gh-pages branch. See: GitHub Docs: Managing a custom domain for your GitHub Pages site

I then configured github pages to publish under a custom domain (lab.bjg.io), this will automatically create a new CNAME file in the root of your project. Next I went to by DNS provider and added a new CNAME record to my domain configuration pointing lab.bjg.io -> bgianfo.github.io.

And Voila! It Alive!

Well kind of … As soon as I pushed new changes, the sub domain no longer works. That is very strange?

After some digging in the CI logs, I realized that the actions-gh-pages action was deleting the CNAME file in the gh-pages branch on every push, breaking the configuration. I looked through the docs for the gh-pages action and found they have their own option for auto generating the CNAME file from within the action. So I made a small change to use that option:

commit 2f5c50ad033f4db4401ba7ddf427306ed326ab2e
Author: Brian Gianforcaro <b.gianfo@gmail.com>
Date:   Tue Dec 29 04:10:11 2020 -0800

    CI: Configure CNAME when generating html and publishing to gh-pages

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 7707376..1364391 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -23,3 +23,4 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./book
+          cname: lab.bjg.io

Brian's Lab Notebook

12-29-2020: Lab Notebook Setup

Introduction

Boot Strapping The Book

Publishing