Astro Loader for Obsidian Vaults 🪐🔗

astro-loader-obsidian is a content loader for Astro that lets you treat your Obsidian vault as a native content collection. Easily integrate your markdown notes, assets, and internal links into your Astro site with minimal setup.

✨ Features

• 📁 Load entire Obsidian vaults as Astro content collections.
• 🔗 Resolves Obsidian-style links into proper Astro/HTML links.
• 🖼️ Image path resolution for local media files (including support for image embeds).
• 📝 Reads frontmatter from your notes and exposes publishing metadata (like published, tags, date, etc).
• ⚡ Supports Astro’s Content Collections API, including types and schema validation.
• 💡 Lightweight and fast — ideal for digital gardens, knowledge bases, blogs, and more.

🚀 Use Cases

• Personal knowledge bases
• Digital gardens
• Developer blogs
• Collaborative wikis

🧰 Need a Full Theme?

Check out astro-theme-spaceship — a ready-to-use theme built specifically for publishing Obsidian vaults with Astro. It includes:

• Preconfigured astro-obsidian-loader integration
• Clean, responsive layout
• Built-in support for tags, backlinks, and note metadata
• Dark mode, tree view, and more

📦 Installation

npm install astro-loader-obsidian

🔧 Usage

1. Setup your Astro config to include the loader:

// content.config.mjs
import { ObsidianDocumentSchema, ObsidianMdLoader } from "astro-loader-obsidian";
import { defineCollection } from 'astro:content';

export const collections = {
	documents: defineCollection({
		loader: ObsidianMdLoader({
			base: 'src/content/vault',
			url: 'docs',
		}),
		schema: ({ image }) => ObsidianDocumentSchema.extend({
      image: image().optional(),
      // or
      cover: image().optional(),
    }),
	}),
};

2. Use your documents as content in Astro components or pages:

import { getCollection } from 'astro:content';

const documents = await getCollection('documents');

3. Linking between notes works automatically:

<a href={document.data.permalink}>Read: {note.data.title}</a>

🧠 Frontmatter Support

Astro Loader respects frontmatter metadata in your Obsidian notes. You can use:

---
title: "My Note"
date: 2025-04-06
tags: [astro, obsidian]
published: true
---

These fields will be accessible via the data object in your content collections.

📁 Directory Structure

Example vault structure:

vault/
├── My Note.md
├── My Other Note.md
├── images/
│   └── image.png

Will be available in Astro as:

/docs/my-note
/docs/my-other-note
/images/image.png

🧪 Type Safety

You can extend the schema for your frontmatter using Zod’s extend features:

// content.config.mjs
import { defineCollection, z } from 'astro:content';

export const collections = {
	documents: defineCollection({
		loader: ObsidianMdLoader({
			base: 'src/content/vault',
			url: 'docs',
		}),
		schema: ({ image }) => ObsidianDocumentSchema.extend({
      image: image().optional(),
      // or
      cover: image().optional(),
      myCustomProperty: z.string().optional(),
    }),
	}),
};

🛠️ Configuration Options

🙌 Contributing

Contributions welcome! Feel free to open issues or PRs for bugs, features, or docs improvements.

📄 License

MIT License © aitorllj93

Built with ☄️ Astro and 🧠 Obsidian