OpenAPI-Writing Documentation in Obsidian

Introduction

If you’re looking for a lightweight, version-controlled, and customizable way to document your APIs, Obsidian + Hugo is a killer combo.

My Favorite actually.. :)

You can write everything in Markdown, generate a fast static site, and self-host your API documentation.

Side Note: Whats also nice about Obsidian, is since everything is in markdown, you can switch between Obsidian and Visual Studio code (for example), very easily..

1️⃣ Setting Up Hugo

Install Hugo

First, install Hugo based on your OS:

Mac (Homebrew):

1
brew install hugo

Windows (Chocolatey):

1
choco install hugo

Linux:

1
sudo apt install hugo

Verify the installation:

1
hugo version

You should see an output like:

1
hugo v0.92.0+extended linux/amd64 BuildDate=...

Create a New Hugo Site

1
2
hugo new site openapi-docs
cd openapi-docs

2️⃣ Choosing an OpenAPI-Compatible Hugo Theme

Hugo doesn’t natively support OpenAPI, but you can use a theme that does!

Recommended OpenAPI Hugo Themes

Theme	Link
Docsy	https://github.com/google/docsy
Learn	https://github.com/matcornic/hugo-theme-learn
DocuAPI	https://github.com/bep/docuapi

Install a Theme

For this guide, we’ll use DocuAPI:

1
2
git submodule add https://github.com/bep/docuapi.git themes/docuapi
echo 'theme = "docuapi"' >> config.toml

3️⃣ Writing OpenAPI Documentation in Obsidian

Organizing Your Files

In Obsidian, structure your API docs like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
📂 openapi-docs/
 ├── 📂 content/
 │   ├── 📄 _index.md
 │   ├── 📂 api/
 │   │   ├── 📄 introduction.md
 │   │   ├── 📄 authentication.md
 │   │   ├── 📄 endpoints.md
 │   │   ├── 📂 schemas/
 │   │   │   ├── 📄 user.md
 │   │   │   ├── 📄 order.md
 ├── 📄 config.toml

Example: Introduction.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
---
title: "Introduction"
description: "Overview of the API"
weight: 1
---

# Welcome to Our API  

This API allows developers to interact with our platform.  

- **Base URL:** `https://api.example.com`
- **Authentication:** API Key in `Authorization` header

4️⃣ Rendering OpenAPI Specs in Hugo

To display OpenAPI specs, you need Redoc or Swagger UI.

Using Redoc (Recommended)

1️⃣ Download Redoc JavaScript

1
2
mkdir -p static/js
curl -o static/js/redoc.standalone.js https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js

2️⃣ Create a Page for OpenAPI Docs
Create content/api/openapi.md and add this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
title: "API Reference"
description: "OpenAPI Specification"
weight: 3
---

# API Reference  

<script src="/js/redoc.standalone.js"></script>
<redoc spec-url="/openapi.yaml"></redoc>

3️⃣ Add Your OpenAPI Spec

Place your openapi.yaml file in static/:

1
mv openapi.yaml static/openapi.yaml

5️⃣ Running Hugo Locally

Start the Hugo development server:

1
hugo server -D

Visit: http://localhost:1313 🎉

6️⃣ Deploying Your OpenAPI Docs

GitHub Pages Deployment

1️⃣ Build the static site:

1
hugo --minify

2️⃣ Push to GitHub:

1
2
3
4
5
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/YOUR_USERNAME/openapi-docs.git
git push -u origin main

3️⃣ Deploy with GitHub Actions

Create .github/workflows/hugo.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
name: Deploy Hugo Site

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      - run: hugo
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

✅ Your site is live on https://YOUR_USERNAME.github.io/openapi-docs/

Alternative Hosting

Service	Link
Netlify	https://www.netlify.com
Vercel	https://vercel.com
Cloudflare Pages	https://pages.cloudflare.com