Andrew Geltz's Blog

How this blog is made

5 min read

About

I recently started using Obsidian to start taking notes for the Dungeons and Dragons games I play as an attempt to organize the session notes into a useable format. It has really helped me quickly jot down notes and then link relevant NPCs, locations, items, etc. without having to jump through hoops of creating a full wiki. I’ve also found it really helpful for it’s search capabilities for quickly jumping back to something that happened in a previous session or the backlinks for quickly finding the context for when we met a specific character directly from their NPC page.

Since I was enjoying using Obsidian, I wanted to share this content with the other players in the group and started looking into different ways to “host” and Obsidian vault. Obsidian has their own hosting option called Publish but that is a paid service and I was planning on creating multiple vaults to keep my notes organized which would cost more in their current pricing model.

After some searching, I came across Quartz. It is a node-based tool that will generate a static site from your Obsidian vault. This means that I can take my notes in the vault and present a read-only copy of it in wiki-like fashion.

Now that I had a tool for how to generate the site, I needed a way to host it. I am pretty familiar with Gitlab and Gitlab CI/CD so I decided to leverage those. Storing the notes in Gitlab meant I get version control and “cloud” storage of the vault so I don’t have to worry about backing the vault up. Gitlab CI/CD will be used to run the Quartz build of the content and we can host the generated site using Gitlab Pages for free.

To recap:

Setup

Pre-requisites

  • Install Obsidian
  • Create a Gitlab account
  • Create a folder on your computer to store this project

Setup steps

  1. Create a repository but do not initialize it with a readme or anything
  2. In the repository Settings > General > Visibility, change the Project visibility from Private to Public, this is required for allowing users to view the site without logging into Gitlab, this does make your repo itself visible so definitely take a look at the other Visibility settings
  3. Open a terminal in your project folder
  4. Run git init to initialize the repository on your local filesystem
  5. Note the url of your repository (e.g. gitlab.com:user/project.git) and run git remote add origin git@<url>
  6. Run git add . and git commit -m "Initial commit"
  7. Install Quartz into your repo as a git subtree git subtree add --prefix quartz https://github.com/jackyzha0/quartz.git v4 --squash
  8. Copy the quartz.config.ts from the quartz directory into the root of your repo, only make changes to this one, we do this so the subtree can stay clean and the quartz.config.ts will be copied into the build during the pipeline
  9. Create a vault in Obsidian, ensure you nest it in inside the folder you created (eg projectroot/Vault)
  10. In your vault, create a folder called Content and create a note called index.md with some placeholder content
  11. Create a file called .gitlab-ci.yml in the root of your project folder with the following content, make sure to update the path to the Content file you created in the previous step
stages:
  - build
 
variables:
  CONTENT_DIR: ../Blog/Content
 
build:
  image: node:20
  stage: build
  cache: # Cache modules in between jobs
    key: $CI_COMMIT_REF_SLUG
    paths:
      - .npm/
  script:
    - echo "Building Quartz..."
    - cp quartz.config.ts quartz/quartz.config.ts
    - cd quartz
    - npm ci --cache .npm --prefer-offline
    - npx quartz build --directory=$CONTENT_DIR --output ../public
  pages: true
  1. Push your changes to GitLab and trigger the pipeline by running git add ., git commit -m "Initial commit", and then git push origin main
  2. In the gitlab console, click the “Pages” button inside the “Deploy” section of the left pane
        - This is where you can see the current url for your pages site and configure how you want the url to work (I prefer turning off the “Use unique domain” setting)

At this point you should have your Obsidian vault backed up in git and your content should be available on Gitlab Pages.

Writing content

In general, writing content is just like taking notes in Obsidian (and there are much better guides than I could write about learning Obsidian). Each note is it’s own page and you can nest notes inside folders as needed. The url path is based on the file path for the notes, for example, a note located <Vault directory>/Content/pages/about.md would be located at <gitlab pages url>/pages/about.

The one exception to this is the homepage, it is located <Vault directory/Content/index.md and will be served when users visit the site root (ie https://<gitlab pages url>/).

Frontmatter

In Obsidian, Frontmatter is like metadata attached to a note. You can leverage frontmatter for many tasks however, Quartz has several properties that are configured for each page using the frontmatter.

The ones I think are most relevant:

  • title the display name of the page, if missing, Quartz uses the file name
  • draft if the value is set to true, the page will be hidden on the generated site
  • date the displayed publish date of a given page, in YYYY-MM-DD format
  • description the description of the page showed in previews

Conclusion

If you’re looking for a lightweight tool for note taking and want to share those notes as a website, using Obsidian, Quartz, and Gitlab can be a free and quick way to get started. If this post helped you, make sure to come up with a secret handshake with a friend of your choice, it’s good for the world.

Graph View