My new blogging workflow works extremely well!

I swear, I didn't imagine to come this far with my current blogging setup with which I am extremely pleased! I will share with you what I have been able to do with my current setup

  1. Set up an obsidian vault with plugins like
    1. \(\LaTeX\) suite3
    2. Longform (for taking care of boilerplate stuff like setting up templates)
    3. Prism theme (for the focused minded)1
    4. Git (plugin)
    5. Footnote Shortcut2
  2. Use mkdocs/material as the SSG of choice, and configure it to my heart's content. Use plugins as per liking, and create custom layouts for the homepage (which IMHO looks pretty cool!)
  3. Create two repositories
    1. Private repo: For all the content, work in progress, config files, custom layouts etc so that in case I can maintain an all-in-one private vault with a single folder docs/ which contains all my publishables.
    2. Public repo: For pushing the built site and using hgup.github.io as its name to allow github pages to work seamlessly. It also houses all the giscus comments.
  4. Create a kickass CICD GitHub Actions file

The GitHub Actions is my favorite part. See I have two requirements (not really requirements, but nice-to-haves).

  1. I have private files in my vault that I don't want to be published or viewed by anyone and also when I push such files to my repository. I don't need the entire site to be built again with no real changes (since I hadn't updated any files within the docs/ folder nor the mkdocs.yml file) and really its bad for the environment (using computing power for nothing)
  2. Whenever I update a file in thedocs/ folder I want the CICD pipeline to run so that the changes can be LIVE on hgup.github.io

This ci.yml actions file does it all!

.github/workflows/ci.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  publish:
    name: Publish
    # The extremely crucial conditional statement (1)
    if: "contains(github.event.head_commit.message, 'docs/') || contains(github.event.head_commit.message, 'mkdocs.yml') || contains(github.event.head_commit.message, 'config')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898xxx+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache 
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: pip install mkdocs-awesome-nav 
      - run: pip install "mkdocs-material[imaging]"

      - name: Build MkDocs site
        run: mkdocs build # This creates the 'site' directory

      - name: Push built files to target repository # (2)
        uses: cpina/github-action-push-to-another-repository@v1.7.2
        env:
          API_TOKEN_GITHUB: ${{ secrets.DEPLOY_PAT }} # Use your secret PAT (3)
        with:
          # Source directory from the origin directory
          source-directory: 'site'
          # Name of the destination username/organization
          destination-github-username: 'hgup'
          # Destination repository
          destination-repository-name: 'hgup.github.io'
          # Email for the git commit
          user-email: 'action@github.com'
          # [Optional] set target branch name for the destination repository. Defaults to "main"
          target-branch: 'gh-pages' # optional, default is main
          # [Optional] create target branch if not exist. Defaults to `false`
          create-target-branch-if-needed: true # optional
          commit-message: 'Site update'
  1. This condition runs the publishing sequence only if the commit message contains the following three strings. docs/,mkdocs.yml and config. I have set up Git on obsidian in such a way that it adds the file names to the description of the commit and thus whenever I update a file in the docs/ folder, it registers and triggers a build. Pretty neat and satisfies the two nice-to-haves above.
  2. The built files are then pushed to my public repository hgup.github.io. This ensures that I don't have to make my entire vault public and only the publishable stuff exists in the public repository.
  3. I am using fine-grained tokens here and only allowed this bot to update the content of this particular repository hgup.github.io. So, I don't need to worry about it being leaked really.

And that's it! Now that I have written this post. I will just commit-and-sync using obsidian and you should be able to see it live on hgup.github.io.

  1. I wanted to enjoy the process of writing and forget that I ever published anything online. I wanted to just open the site one day feel surprised "Wow! All this exists??" ↩

  2. (with a keyboard shortcut Alt+Q) which I used to create this footnote too ↩

  3. This also contains many snippets that allows me to utilize mkdocs's extra features without remember syntax too much. ↩

Comments