Obsidian: Markdown Knowledge Base

Obsidian is a powerful knowledge base that works on top of a local folder of plain text Markdown files—making it a perfect editor for HugoBlox.

Vault Structure

For the best developer experience (DX) and portability, we recommend organizing content into Leaf Bundles (self-contained directories). This keeps your post and its assets (images, graphs, notebooks) together.

• Directorycontent/

  • Directoryblog/

    • Directorymy-amazing-post/

      • index.md (The Content)
      • cover.jpg (Specific Asset)
      • graph.json (Specific Asset)
    • Directoryanother-post/

      • index.md
      • screenshot.png

Configure Obsidian for HugoBlox

To make Obsidian play nicely with this structure, adjust these settings:

1. File & Link Settings

Go to Settings → Files & Links:

Default location for new attachments

Set to “Same folder as current file”.

Why: When you drag an image into a post, it saves directly alongside the markdown file (e.g., inside my-amazing-post/), keeping the bundle self-contained.

Use Wikilinks

Uncheck (Turn Off).

Why: Forces standard Markdown links ![](image.png) instead of ![[image.png]]. Standard Markdown is portable and works natively with Hugo, GitHub, and other tools.

2. Recommended Plugins

Enhance your workflow with these community plugins:

• Folder Note (or similar): Allows you to click a folder (like my-amazing-post) and edit the index.md inside it automatically. This bridges the gap between Obsidian’s folder view and Hugo’s file structure.
• Image Converter: Automatically converts pasted images to WebP or compressed JPEG to keep your repo light.
• Linter: Can automatically format frontmatter or other markdown syntax on save.

Workflow

1. Open Vault Open your project’s root folder (or content/ folder) as an Obsidian Vault.

2. Create Content

   • Create a New Folder for your post (e.g., content/blog/my-new-post).
   • Inside it, create a New Note named index.
   • Tip: Use the “Folder Note” plugin to automate this.

3. Add Frontmatter Add your Hugo frontmatter to the top of index.md:

   ---
   title: My New Post
   date: 2025-01-01
   authors: [admin]
   ---

4. Write & Drag Assets Write your post. Drag and drop images, PDFs, or JSON files directly onto the editor. Obsidian will place them in the same folder.

5. Commit Your post and all its assets are now in one tidy folder. Commit and deploy!