publishing-with-obsidian

How I publish my notes with Obsidian

If you’re using Obsidian for your daily notes and have an own home server (and who hasn’t an own home server in the age of BIG TECH? Hugh?), then you can easily use the MkDocs to convert your notes into static html files and upload them on your server, where they can be read by the whole world. Well, you should be aware, what you are actually publishing…

Anyway, let’s get started! Or just use Quartz4!

Install and config MkDocs

First, I don’t want to publish all my notes, so I create a folder Public, where my notes, relevant for publishing, are stored.

In the Obsidian vault root, run the following:

python3 -m venv .venv && source .venv/bin/activate
pip install mkdocs-terminal mkdocs-roamlinks-plugin mkdocs-glightbox mkdocs-mermaid2-plugin pymdown-extensions

and create the file mkdocs.yml:

site_name: My Notes
theme:
  name: terminal
  features:
    - navigation.instant
    - content.code.copy
    - search.suggest
    - search.highlight
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.critic
  - pymdownx.tasklist
  - attr_list
  - tables
  - pymdownx.arithmatex:
      generic: true
plugins:
  - search
  - roamlinks:
      wikilinks: true # supports [[Wiki Links]]
  - glightbox
  - mermaid2
docs_dir: site-src      # this is where we'll copy/convert notes for publishing
extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

Write the publishing script

Also create a publish.sh (and make it executable with chmod +x publish.sh):

#!/usr/bin/env bash
set -euo pipefail
 
# 1) Clean build dir
rm -rf site-src
mkdir -p site-src
 
# 2) Strategy A: publish a whole folder
# rsync the Public folder (adjust if you prefer frontmatter filtering below)
rsync -av --exclude ".obsidian" --exclude "node_modules" "Public/" "site-src/"
 
# 3) Build site
source .venv/bin/activate && mkdocs build -q
 
# 4) Deploy to your server over SSH (adjust host, user, path)
# Serve the built HTML from 'site/' on your server (nginx/Apache/Caddy)
rsync -az --delete site/ odroid:/usr/share/obsidian-notes
 
# 5) Cleanup
rm -rf site site-src

Trigger from Obsidian

Install the commity plugin Shell commands and add the command to publish your notes and enter the path to the publish.sh. This way, you can conveniently publish your notes from Obsidian, without using the terminal. You can configure the command and under Output, a notification can be enabled, which can be shown, until the process finished.

Prepare your home server

I use caddy to serve applications running in docker or to server static files. The latter is what we are using here. Add to your Caddyfile the lines

notes.your-domain.com {
  root * /usr/share/obsidian-notes
  file_server
  encode zstd gzip
}

and don’t forget to reload caddy!

Create an index file

Back in Obsidian, you should create a file index in the Public folder. This is the file you see, when you visit your homepage. For now, I just index my other files there, but it should be a more welcoming page 🙂

Finish

Run your publish.sh from Obsidian and hope, that everything works well!