Skip to content

Obsidian + MkDocs + Cloudflare

This guide shows how to integrate Obsidian (for writing), MkDocs (for static site generation), and Cloudflare Pages (for deployment).

1. Obsidian Configuration

  • Open the repository root as a vault.
  • Settings → Files & Links
    • New link format: Relative path to file
    • Use [[Wikilinks]]: Off
    • Default location for new attachments: docs/img
  • Linking rules
  • Always use relative links, e.g.
    markdown ![Example](../img/taggingmanager.excalidraw.svg)
  • Avoid leading slashes like /img/....
  • Download community plugin: "Excalidraw"
  • Drawing
    • Go to Excalidraw settings -> Embedding Excalidraw Into Your Notes And Exporting -> Export Settings -> Auto Export Settings -> "Auto-export SVG" and "Keep the SVG. in sync with the drawing file" both toggle on
    • This settings will enable you have the ability to draw in Excalidraw directly in Obsidian and every change will be automatically exported to SVG file that can be linked in your notes (Eraser type of functionality by 10x better)
  • After editing excalidraw chart, don't forget to run save command (cmd + s) to immediately update the svg file

2. MkDocs

We have chosen mkdocs for its simplicity. First install the mkdocs by defining requirements.txt file:

mkdocs
mkdocs-material

Run this

pip install -r requirements.txt

# preview locally
mkdocs serve   # open http://127.0.0.1:8000

# build static site
mkdocs build   # output in ./site

Configure mkdocs.yml:

mkdocs.yml

site_name: Skyll Docs
site_url: https://skyll.docupreview.uk

theme:
  name: material
  features:
    - navigation.instant
    - navigation.sections
    - navigation.tracking
    - content.code.copy
nav:
  - Description: index.md
  - Phases:
      - Phase 1: phases/phase-1.md
      - Phase 2: phases/phase-2.md
  - Features:
      - Tagging manager: features/tagging-manager.md
  - Technical:
      - Cloudflare: technical/cloudflare.md
      - How To Prepare Analysis: technical/analytical-tools.md

markdown_extensions:
  - toc:
      permalink: true
  - admonition
  - footnotes
  - tables
  - attr_list
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com
plugins:
  - search

docs_dir: docs

After you are happy with your layout, you can always run the command below to test if your site does not produce any errors. If it does produce errors, the build process of Cloudflare will most likely fail so always check this first.

mkdocs serve
mkdocs build

3. Cloudflare

After you happy with local preview from mkdocs, pushing to github.com:axia-futures/documentation.git publishes to https://skyll.docupreview.uk within ~5 minutes.