Obsidian on

Front Matter Is the Schema of Your Knowledge Base

Sun, 19 Apr 2026 00:00:00 +0000

Front Matter Is the Schema of Your Knowledge Base

There is a Dataview query I run at least once a week:

TABLE date, author, genre
FROM "30-books"
WHERE contains(tags, "non-fiction") AND status = "finished"
SORT date DESC

It gives me a table of every non-fiction book I have finished, when I completed it, and who wrote it — in about 200 milliseconds. When I want to find what I read on a specific topic, I do not dig through folders or search my memory. I run the query.

That query only works because every note in that folder has structured front matter. Without it, Dataview has nothing to read, and the query returns zero results. I would be back to scrolling through files, reading titles, hoping I named things consistently.

That is not a trivial difference. It is the difference between a note-taking app and a knowledge base.

The Unstructured Vault Problem

Most people start Obsidian the same way: create a folder structure, drop notes in, link a few things. It feels organized at first. Folders give the illusion of structure.

The problem is that folders are physical storage, not logical structure. A note about a book you finished sits in 47-books/. That tells you where the file lives. It tells you nothing about when you read it, whether you finished it, who wrote it, what genre it is, or whether it connects to three other books you read on the same topic in a different folder.

Worse, that knowledge is invisible to anything that tries to read your vault programmatically. Dataview cannot query it. A PAI skill cannot filter for it. An AI context loader cannot select it by relevance. The information exists, but it is locked inside prose — retrievable only by a human reading the file.

When your vault grows past a few hundred notes, that model collapses.

What Front Matter Actually Is

Front matter is a YAML block at the top of a markdown file, delimited by triple dashes. It holds structured key-value pairs that describe the note — not the content itself, but metadata about it.

It is not magic and it is not complicated. It is a schema.

A minimal front matter block for a knowledge base note might look like this:

---
title: "Thinking, Fast and Slow"
date: 2026-03-12
tags:
 - non-fiction
 - psychology
 - behavioral-economics
status: finished
author: Daniel Kahneman
rating: 5
---

Three fields do most of the work: tags (what domain and type is this), date (when), and a status or type field (where in its lifecycle). Everything else is optional until a specific query demands it.

What It Unlocks

Dataview queries. Once your notes have consistent front matter, Dataview turns your vault into a queryable database. You can build a live table of unresolved issues, a list of certification notes by module, a filtered view of blog drafts not yet published. The query language is simple. The payoff is immediate.

Cross-domain filtering. My vault spans four domains: career notes, AI governance certification notes, PAI infrastructure documentation, and blog post drafts. Without front matter, navigating across those domains means folder-hopping. With front matter, I can query across all four simultaneously — surface everything tagged behavioral-economics regardless of where it lives, or find all notes with status: in-progress across every section at once. The folder structure stays for physical organization. Front matter handles the logical layer.

AI context loading. This is the one that changed how I think about it. PAI does not load my entire vault into context when I ask a question about something I have read. It loads notes that match specific criteria: the right tags, the right domain, the right status. That selection mechanism is front matter. Without structured metadata, the system gets everything or nothing. With it, loading can be precise.

Before and After: The Same Note

Without front matter:

# Thinking, Fast and Slow
Really good book. Kahneman breaks down how we make decisions — System 1
is fast and intuitive, System 2 is slow and deliberate. The section on
cognitive biases was the most useful part. Finished it in March. Would
recommend to anyone interested in decision-making or behavioral economics.

This is a fine note. It has the information. But Dataview cannot surface it in a query. PAI cannot identify it as a finished book on behavioral economics. Six months from now, I will not remember I wrote it unless I happen to search the right words.

With front matter:

---
title: "Thinking, Fast and Slow"
date: 2026-03-12
tags:
 - non-fiction
 - psychology
 - behavioral-economics
 - decision-making
status: finished
author: Daniel Kahneman
rating: 5
---

Now the note is queryable. PAI surfaces it automatically when I ask about books on decision-making. Dataview includes it in my Q1 reading table. I can filter for all five-star books across my entire reading folder. The content of the note is identical — only the schema changed.

The Architecture Argument

A relational database without a schema is just a collection of text files. An Obsidian vault without front matter is nearly the same thing — a sophisticated folder system with backlinks and a graph view, but still fundamentally unqueryable by anything that needs to select notes by attribute.

Front matter gives your vault a schema. Folders give it a physical address. You need both, but the schema is what makes a vault a knowledge base. Without it, you are building a library where every book is correctly shelved but nothing has a catalog entry. Finding anything specific means walking the stacks and reading spines.

Where to Start

Do not design an elaborate front matter schema before you have written a hundred notes. That is premature optimization and it will not survive contact with actual usage.

Start with three fields: tags, date, and status. Add type if your notes serve different purposes (reference, log, draft, fix-doc). Add domain-specific fields only when a query demands them.

The schema should be pulled from how you actually search, not pushed from how you think you might want to search someday. Write the notes, run queries against three fields, and let the gaps tell you what to add next. The vault teaches you what it needs — if you have given it enough structure to communicate.

Deploying a Hugo Site to Namecheap with PAI

Sun, 15 Feb 2026 00:00:00 +0000

I recently deployed my Hugo blog to Namecheap shared hosting, using Obsidian as my content editor and Claude Code with PAI (Personal AI) as my copilot. Here’s a walkthrough of every step, from fixing build errors to setting up a fully automated pipeline that goes from Obsidian to live site in a single command.

The Starting Point

I created a Hugo blog project called Augmented Resilience and used the re-terminal theme, a Namecheap shared hosting account, and a GitHub repository. I used Claude Code in VS Code editor and leveraged Daniel Miessler’s Personal AI infrastructure. The goal: get the site live at augmentedresilience.com with a push-to-deploy workflow.

For context, the Personal AI Infrastructure System (PAI) from Daniel Miessler (see resources below) is an open-source framework that wraps around Claude Code and turns it into a structured problem-solving system. Instead of just chatting with an AI, PAI runs every request through a 7-phase algorithm — observe, think, plan, build, execute, verify, learn — so nothing gets skipped. It maintains persistent memory across sessions (so it remembers my project structure, preferences, and past decisions), automatically selects specialized agents for different tasks (security review, architecture, engineering), and enforces verification criteria before declaring anything “done.” For this project, PAI handled everything from debugging Hugo build errors to writing the deploy script to catching sensitive data I accidentally left in this blog post before it went live. It wasn’t just an AI assistant — it was the entire workflow engine. I found it easier to use it within VS Code (still getting used to using the command line interface).

Step 1: Fixing the Hugo Build

The first issue was a build error:

module "hugo-theme-re-terminal" not found

The problem was a mismatch between the theme name in hugo.toml and the actual directory name. The theme was installed as a git submodule at themes/re-terminal/, but the config referenced hugo-theme-re-terminal.

Fix: Change the theme name in hugo.toml:

theme = "re-terminal"

After that, hugo built the site successfully, generating the public/ folder with all the static files.

Step 2: Setting Up the GitHub Repository

I initialized the repo and connected it to GitHub:

git init
git remote add origin git@github.com:dsacosta/Augmented-Resilience.git
git add .
git commit -m "my first commit"
git push origin main

One gotcha: I initially typed orgin instead of origin in the remote add command. Typos happen — double-check your remote names with git remote -v.

Step 3: Connecting Namecheap to GitHub via SSH

This was the trickiest part. Namecheap shared hosting needs an SSH key to clone from a private GitHub repo. Here’s what worked:

Generate an SSH Key on Namecheap

Log into cPanel on Namecheap
Go to SSH Access → Manage SSH Keys → Generate a New Key
Generate an RSA key (I used the default settings)

Remove the Passphrase

This is critical. cPanel’s Git Version Control runs non-interactively, so it can’t prompt for a passphrase. I opened cPanel Terminal and ran:

ssh-keygen -p -f ~/.ssh/id_rsa

Enter the old passphrase, then press Enter twice for no new passphrase.

Add the Public Key to GitHub

On Namecheap’s cPanel Terminal, run: cat ~/.ssh/id_rsa.pub
Copy the output
Go to your GitHub repo → Settings → Deploy Keys → Add deploy key
Paste the public key and save

Verify the Connection

From cPanel Terminal:

ssh -T git@github.com

You should see: Hi dsacosta/Augmented-Resilience! You've successfully authenticated...

Step 4: Clone the Repo on Namecheap

In cPanel, go to Git Version Control → Create
Toggle Clone a Repository on
Enter the clone URL: git@github.com:dsacosta/Augmented-Resilience.git
Set the repository path (I used /home/yourusername/your-repo)
Click Create

Important: Don’t clone directly into public_html or your domain folder — it likely already has files and will error out. Clone to a separate directory and use deployment to copy files over.

Step 5: Auto-Deployment with .cpanel.yml

cPanel supports automatic deployment tasks via a .cpanel.yml file in the repo root. This file tells cPanel what to do after each pull:

---
deployment:
 tasks:
 - export DEPLOYPATH=/home/yourusername/yourdomain.com/
 - /bin/cp -R public/* $DEPLOYPATH

This copies everything from the public/ folder (Hugo’s build output) into the live site directory.

After pushing this file to GitHub:

Go to Git Version Control → Manage your repo
Click the Pull or Deploy tab
Click Update from Remote to pull the latest
Click Deploy HEAD Commit to trigger the .cpanel.yml tasks

Your site should now be live.

Step 6: Fully Automated Deploys with GitHub Actions

To eliminate the manual “pull and deploy” step in cPanel, I set up a GitHub Actions workflow that SSHs into Namecheap and triggers the pull automatically on every push.

Generate a Deploy Key

On your local machine, generate a key pair with no passphrase:

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/deploy_key -N ""

Add the public key to Namecheap:

# In cPanel Terminal on Namecheap:
echo "ssh-ed25519 AAAA...your-key-here github-actions-deploy" >> ~/.ssh/authorized_keys

Add Secrets to GitHub

Go to your repo → Settings → Secrets and variables → Actions and add:

Secret	Value
`NC_HOST`	`augmentedresilience.com`
`NC_USER`	Your cPanel username
`NC_PORT`	Your SSH port (check cPanel)
`NC_SSH_KEY`	The full private key (including BEGIN/END lines)

Create the Workflow

Add .github/workflows/deploy.yml to your repo:

name: Deploy to Namecheap

on:
 push:
 branches: [main]

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - name: Deploy via SSH
 uses: appleboy/ssh-action@v1
 with:
 host: ${{ secrets.NC_HOST }}
 username: ${{ secrets.NC_USER }}
 key: ${{ secrets.NC_SSH_KEY }}
 port: ${{ secrets.NC_PORT }}
 script: |
 cd ~/your-repo && git pull origin main && /bin/cp -R public/* ~/yourdomain.com/

Now every push to main automatically deploys to your live site.

Step 7: One-Command Deploy Script

Five manual commands every time you publish? That’s not a workflow — that’s a chore. I had Claude write a Python script that handles everything in one shot:

#!/usr/bin/env python3
"""One-command deploy: Obsidian → Hugo → GitHub → Live site."""

import subprocess
import sys
from datetime import datetime

PROJECT_DIR = "~/Documents/Augmented-Resilience"
OBSIDIAN_POSTS = "~/projects/obsidian-vault/30-projects/augmented-resilience-posts"
HUGO_POSTS = f"{PROJECT_DIR}/content/posts"


def run(cmd, description, cwd=PROJECT_DIR):
 """Run a command and print status."""
 print(f"\n{'='*50}")
 print(f" {description}")
 print(f"{'='*50}")
 result = subprocess.run(cmd, shell=True, cwd=cwd)
 if result.returncode != 0:
 print(f"\n FAILED: {description}")
 sys.exit(1)
 return result


def main():
 msg = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else f"Site update {datetime.now().strftime('%Y-%m-%d %H:%M')}"

 run(f'rsync -av --delete "{OBSIDIAN_POSTS}" "{HUGO_POSTS}"', "Syncing posts from Obsidian")
 run(f"python3 {PROJECT_DIR}/images.py", "Processing images")
 run("hugo", "Building site with Hugo")
 run("git add .", "Staging changes")

 result = subprocess.run("git diff --cached --quiet", shell=True, cwd=PROJECT_DIR)
 if result.returncode == 0:
 print("\n No changes to commit. Site is up to date.")
 return

 run(f'git commit -m "{msg}"', "Committing")
 run("git push origin main", "Pushing to GitHub")

 print(f"\n{'='*50}")
 print(" DEPLOYED! Your site will be live shortly.")
 print(f"{'='*50}\n")


if __name__ == "__main__":
 main()

Save this as deploy.py in your project root. Now the entire workflow is:

# Default timestamped commit message
python3 deploy.py

# Or with a custom message
python3 deploy.py "Add new blog post about deployment"

The script runs every step in sequence — syncs from Obsidian, converts image links, builds with Hugo, commits, and pushes. If any step fails, it stops immediately so you don’t push a broken build. Combined with the GitHub Actions workflow from Step 6, pushing triggers the auto-deploy to Namecheap. One command, fully live.

Lessons Learned

SSH passphrases break cPanel automation. Always remove the passphrase from keys used by cPanel’s Git Version Control.
Theme names must match directory names. Hugo looks for the theme in themes/<theme-name>/, so the theme value in your config must match exactly.
Don’t clone into the live site directory. Clone to a separate folder and use .cpanel.yml to copy the built files over.
GitHub Actions + SSH is the cleanest auto-deploy for shared hosting. No webhooks, no cron jobs — just a simple SSH action that runs on every push.
Claude Code with PAI made this possible in a single session. From debugging build errors to SSH key troubleshooting to writing GitHub Actions workflows, having an AI pair programmer turned what could have been hours of Stack Overflow rabbit holes into a smooth, guided process.

Tools Used

Hugo — Static site generator
re-terminal theme — Hugo theme
Namecheap — Shared hosting with cPanel
GitHub Actions — CI/CD automation
Claude Code — AI pair programmer
Personal AI Infrastructure (PAI) — Workflow engine
Obsidian — Content authoring
VS Code - Development environment; used as the workspace for Claude Code sessions

Resources

I started a blog…..in 2024 (why you should too) — The YouTube video that inspired me to start this blog
Building a Personal AI Infrastructure (PAI) — Daniel Miessler’s guide to building your own Personal AI system