Back
gh

GoyoStach/Obsidian-to-Astro

Contribute to GoyoStach/Obsidian-to-Astro development by creating an account on GitHub.

by GoyoStach github.com 1,580 words
View original

Obsidian to Astro

© 2021-2026 Guillaume Excoffier. All rights reserved.

A powerful sync tool that transforms your Obsidian notes into a beautiful Astro blog with automated image processing and link conversion.

✨ Features

🚀 Quick Start

Prerequisites

Installation

  1. Clone the repository 
    git clone https://github.com/GoyoStach/Obsidian-to-Astro.git
cd Obsidian-to-Astro
  2. Install dependencies 
    npm install
  3. Configure environment variables Copy the example environment file: 
    cp .env.local.example .env.local
    Edit .env.local with your paths: 
    # Absolute path to your Obsidian vault
OBSIDIAN_PATH=/home/goyo/Documents/Obsidian
# Relative path to blog posts (from project root)
PROJECT_PATH=src/content/blogPost
# Relative path to images (from project root)
IMAGE_PATH=src/Images
  4. Run the development server 
    npm run dev
    Open http://localhost:4321 in your browser.

🧾 About

This project transforms Obsidian notes into a production-ready blog. Inspired by Takuya Matsuyama ‘s workflow:

# How to create a 'What I Use' blog with Astro and Tailwind CSS

Current Version: Astro 5.x with latest features:

📚 Tech Stack

📁 Project Structure

Obsidian-to-Astro/
├── scripts/
│   └── obsidian-sync/        # Sync CLI tool
│       └── src/
│           ├── cli/           # Command-line interface
│           ├── lib/           # Core processing logic
│           │   ├── file-system.ts
│           │   ├── frontmatter.ts
│           │   ├── image-processor.ts
│           │   ├── processor.ts
│           │   └── transformer.ts
│           └── utils/         # Helper functions
├── src/
│   ├── Images/                # Processed images from Obsidian
│   │   ├── preserved/         # Protected from purge
│   │   │   └── astro_banner.png
│   │   ├── hero.png
│   │   ├── image1.png
│   │   └── .gitkeep
│   ├── components/            # React/Astro components
│   ├── layouts/               # Page layouts
│   ├── pages/                 # Route pages
│   │   ├── index.astro
│   │   └── [...slug].astro
│   └── content/
│       └── blogPost/          # Synced markdown files
│           ├── advanced-git.md
│           └── .gitkeep
├── .env.local                 # Environment configuration
├── astro.config.mjs          # Astro configuration
└── package.json

Key Directories

🧞 Commands

All commands are run from the root of the project:

CommandAction
npm installInstall dependencies
npm run devStart dev server at localhost:4321
npm run buildBuild production site to ./dist/
npm run previewPreview built site locally
npm run syncSync Obsidian notes to Astro
npm run sync:cleanClean all synced content (with confirmation)
npm run lintRun ESLint
npm run lint:fixFix ESLint errors automatically
npm run formatFormat code with Prettier

🚀 Deployment

Production Build

Build the site for production:

npm run build

This generates a static site in ./dist/ that can be deployed anywhere.

Automated Deployment

This blog uses automated deployment with Coolify on a VPS:

  1. Sync your Obsidian notes: 
    npm run sync
  2. Commit the changes: 
    git add .
git commit -m "Add new blog post"
git push origin main
  3. Deploy - The CI/CD pipeline automatically builds and deploys

Live Site: https://blog.goyostash.com/

Manual Deployment

You can deploy to any static hosting service:

🛠️ How It Works

Sync Process

When you run npm run sync, the tool:

  1. Discovers markdown files in your Obsidian vault
  2. Filters for files with isExposed: true in frontmatter
  3. Purges old content from src/content/blogPost/ and src/Images/ (except preserved/)
  4. Processes each file:
    • Transforms wiki links: [[Note]] → [Note](/note)
      • Extracts hashtags: #code → added to tags array
      • Resolves hero images from vault
      • Copies hero images to src/Images/
      • Processes content images
      • Updates image references
      • Generates missing frontmatter fields
  5. Writes processed files to src/content/blogPost/
  6. Reports statistics (files processed, images copied, links converted)

Path Resolution

The tool intelligently resolves image paths:

Obsidian: 9999 Images/Advanced_Git/hero.jpg
          ↓
Astro:    src/Images/Advanced_Git_hero.jpg
          ↓
Frontmatter: ../../Images/Advanced_Git_hero.jpg

It handles:

📋 Best Practices

Obsidian Organization

Image Management

Content Writing

🐛 Troubleshooting

Images not showing up

Sync not finding notes

Build errors

📄 License

© 2021-2026 Guillaume Excoffier. All rights reserved.

🙏 Credits

📝 Obsidian Setup

Vault Structure

Your Obsidian vault can have any structure. The sync tool will automatically discover and process marked files:

MyObsidianVault/
├── .obsidian/
├── 200 Informatique/
│   └── 210 Web Dev/
│       ├── Advanced Git.md          # Your blog post
│       └── Multiple git account.md
├── 9999 Images/                     # Optional: centralized images
│   ├── Advanced_Git/
│   │   └── Advanced_Git_hero.jpg
│   └── Multiple_git_account/
│       └── hero.png
└── 800 Miscellaneous/
    └── Another post.md

Frontmatter Configuration

To expose a note as a blog post, add frontmatter with isExposed: true:

---
title: My Awesome Post
description: A brief description of the post
isExposed: true
date: '2026-02-14'
tags:
  - code
  - tutorial
categories:
  - "[[gh]]"
heroImage: 9999 Images/My_Post/hero.jpg
---
# My Awesome Post

Your content here...

Frontmatter Fields

FieldRequiredDescriptionExample
isExposed✅ YesMust be true to sync this noteisExposed: true
title❌ NoPost title (auto-generated from H1 or filename if not provided)title: Advanced Git
description❌ NoPost description (auto-generated if not provided)description: Learn advanced git
date❌ NoPublication date (uses file modification date if not provided)date: '2026-02-14'
tags❌ NoArray of tags (hashtags from content are auto-extracted)tags: [code, git]
heroImage❌ NoPath to hero image in Obsidian vault (uses default if omitted)heroImage: 9999 Images/Post/hero.jpg

Hero Image Paths

The sync tool supports multiple hero image path formats:

# Obsidian centralized images folder
heroImage: 9999 Images/Advanced_Git/Advanced_Git_hero.jpg

# Relative to note location
heroImage: attachments/hero.png

# Subfolder structure
heroImage: Images/My_Topic/banner.jpg

The tool will:

  1. Resolve the image path from your Obsidian vault
  2. Copy it to src/Images/ in the Astro project
  3. Update the frontmatter with the correct relative path: ../../Images/hero.jpg

Image References in Content

Use standard Obsidian syntax for images:

# Obsidian wiki links (recommended)

![[image.png]]
![[folder/image.png]]

# Standard markdown

![Alt text](path/to/image.png)

The sync tool automatically:

Link to other notes using Obsidian wiki links:

# Simple link

[[Other Note]]

# Link with custom text

[[200 Informatique/210 Web Dev/Advanced Git|Git Tutorial]]

# Folder paths are automatically handled

[[Folder/Subfolder/My Note]]

The sync tool converts these to proper URLs:

Creating a New Post

  1. Create a markdown file anywhere in your Obsidian vault
  2. Add frontmatter with isExposed: true: 
    ---
isExposed: true
title: My New Post
description: This is my new blog post
tags: [tutorial, code]
heroImage: 9999 Images/My_New_Post/hero.jpg
---
  3. Write your content using Obsidian features:
    • Wiki links for internal references
      • ![[image]] for images
      • #hashtags for additional tags
      • Standard markdown formatting
  4. Run the sync command: 
    npm run sync

The tool will:

Sync Workflow

# 1. Sync from Obsidian to Astro
npm run sync

# 2. Preview changes locally
npm run dev

# 3. Build for production
npm run build

# 4. (Optional) Clean all synced content
npm run sync:clean

Protected Images

Images in src/Images/preserved/ are never deleted during sync cleanup. Use this folder for:

Example:

heroImage: ../../Images/preserved/astro_banner.png