Blog / Engineering
tutorial

Publishing Obsidian.md notes with GitLab Pages

Scott Hampton ·
Mar 15, 2022 · 10 min read · Leave a comment
Scott Hampton GitLab profile

Obsidian.md is a "knowledge base" application that uses plain text Markdown files stored in a local folder to organize your notes. The product has been growing in popularity, partly because of how extensible it is. There are a lot of community built plugins to help users configure the application to support their specific workflow. There are many people that use Obsidian to write their blog posts. Obsidian offers a paid service to publish your notes directly and is completely compatible with features Obsidian offers. I suggest you support the Obsidian developers if their product works for you. If you are looking for an alternative way to publish, this blog post provides a tutorial for how to publish your notes using GitLab Pages.

You can find an Obsidian.md example in this demonstration project which deploys a GitLab Pages site.

Introduction to Obsidian.md

Obsidan.md, at it's core, is an application that helps manage your markdown files. You can download the application via their site and create a "workspace" folder when you first start the application. When using the application, all of your notes will be created in the folder you choose as your "workspace".

Obsidian application

Workspace file structure

Inside your Obsidian workspace, you can have any number of folders and markdown files. When you open a folder in Obsidian as your "workspace", Obsidian will automatically add a folder .obsidian, which contains your workspace configuration such as application styles and plugins. A basic workspace file structure could look something like this:

.
├── workspace_folder/
│   └── Other pages/
│   │   └── Another page.md
│   └── .obsidian
│   └── index.md

index.md

# Home

This is a basic home page, and a link to another page in my documents.

See [[Another page]] - note that this link uses wikilinks which Obsidian uses to help you easily link to other notes in your workspace.

Other pages/Another page.md

# Another page

This is another page besides the home page.

Generating a static site to host your notes

In order to publish your notes to GitLab Pages, you need to create a static site to show and navigate your notes. There are several open source tools that generate static sites from Markdown documents. After experimenting with a few, I found MkDocs to be the easiest and most compatible with Obsidian.

If you would like to use MkDocs locally, you can install it with pip install mkdocs (Python and pip as package manager are required). This is not necessary, because in this tutorial we'll utilize GitLab CI pipelines to install MkDocs and build our site.

There are two small steps you need to make in order to get your existing Obsidian notes working with MkDocs.

File structure

All files that are not your workspace notes will be created outside of your workspace folder. The following folder structure is how this final demo project is going to look.

.
├── wiki/
│   └── .obsidian
│   └── index.md
├── .gitlab-ci.yml
├── mkdocs.yml
└── requirements.txt

Basic MkDocs Configuration

You'll need to create a configuration file mkdocs.yml for MkDocs to know how you would like your site to look. Here are the first four lines we need to configure our notes.

site_name: My Obsidian Notes
site_url: https://group-name.gitlab.io/repo-name
site_dir: public
docs_dir: ./wiki

We'll come back to this configuration file later to add more custom styles to your site.

Configuring GitLab CI

We need to configure a GitLab CI job to install MkDocs and build the web site based on our Obsidian notes. The following .gitlab-ci.yml file has the basic setup for this:

image: python:3.8-slim

pages:
  stage: deploy
  script:
    # Install all of the python packages for mkdocs
    - pip install -r requirements.txt
    # Build the site using mkdocs
    # --strict aborts the build on any warnings
    # --verbose enables verbose output so that it's easier to see what mkdocs is doing
    # neither --strict nor --verbose are necessary if you choose not to use them
    - mkdocs build --strict --verbose
  artifacts:
    paths:
      - public
  only:
    - main

This job will only run when a change is made to the default branch (main in this case).

Python Packages

Note the line pip install -r requirements.txt in the above .gitlab-ci.yml file. This line is installing MkDocs and any additional plugins you use to customize your site. You'll need to create a requirements.txt file for this script to work:

# Documentation static site generator & deployment tool
mkdocs>=1.1.2

We'll come back to this requirements.txt file to add a couple more packages to customize our site later.

Customizing your site

One of the benefits of using MkDocs is that it has a lot of extensions you can add on to customize your site. You can change the theme of the site, which adjusts the colors and layout. You can also add extensions that improve how your markdown notes are displayed and interacted with on the site.

Theme

MkDocs includes two built-in themes (mkdocs and readthedocs), as documented on their website. There are also a lot of community built themes you can search through and choose to use. My current favorite theme is Material. You can install it by adding it our requirements.txt and choosing it as your theme in the mkdocs.yml configuration file, or if you are installing it locally you can install it with pip install mkdocs-material.

requirements.txt

# Material theme
mkdocs-material>=8.1.7

mkdocs.yml

theme:
  name: material
  palette:
    scheme: slate

I have chosen the slate scheme for the material theme which makes it darker. You can choose more configuration options based on their website documentation.

Extensions

MkDocs includes built-in extensions that you can add to your mkdocs.yml configuration file. The Material theme package also comes with many more extensions that we can use. Below are some of my favorite for working with Obsidian:

# Extensions
markdown_extensions:
  - footnotes
  - attr_list
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.details
  - pymdownx.magiclink
  - pymdownx.tasklist
  - pymdownx.emoji
  - admonition
  - toc:
    permalink: true

Plugins

MkDocs also has a community of plugins that add more features when building your site. MkDocs includes some plugins by default that you can use in the configuration file, but in order to use community plugins you have to add them to the requirements.txt file to be installed as packages. The following two plugins are ones that I've found useful, but you can look at the list of community plugins here:

plugins:
  - search
  - roamlinks

requirements.txt

# Wikilinks support
mkdocs-roamlinks-plugin>=0.1.3

If installing locally, you can install roamlinks with pip install mkdocs-roamlinks-plugin.

Combining it all together

After all of the above work is done, you should have a file structure that looks like this:

.
├── wiki/
│   └── .obsidian
│   └── index.md
├── .gitlab-ci.yml
├── mkdocs.yml
└── requirements.txt

Here are the contents of the three main files that you've been editing:

.gitlab-ci.yml

image: python:3.8-slim

pages:
  stage: deploy
  script:
    - pip install -r requirements.txt
    - mkdocs build --strict --verbose
  artifacts:
    paths:
      - public
  only:
    - main

mkdocs.yml

site_name: My Obsidian Notes
site_url: https://group-name.gitlab.io/repo-name
site_dir: public

theme:
  name: material
  palette:
    scheme: slate

# Extensions
markdown_extensions:
  - footnotes
  - attr_list
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.details
  - pymdownx.magiclink
  - pymdownx.tasklist
  - pymdownx.emoji
  - admonition
  - toc:
    permalink: true

plugins:
  - search
  - roamlinks

requirements.txt

# Documentation static site generator & deployment tool
mkdocs>=1.1.2

# Material theme
mkdocs-material>=8.1.7

# Wikilinks support
mkdocs-roamlinks-plugin>=0.1.3

Now that your files are all finished, the last step is to push your changes to your GitLab repository and wait for your pipeline to finish. Once finished, you can go to your default domain provided by GitLab or you can configure GitLab Pages to use a custom domain.

Here's a screenshot of the demonstration site created in this tutorial:

Obsidian application

Share your Obsidian.md deployments in the comments.

Open in Web IDE View source