Skip to main content

Writing Blog Posts with Obsidian and Git

· 6 min read
BENE Maël
BENE Maël
System Administrator

How I configured Obsidian with the Git plugin to write and synchronize my blog posts and technical documentation, with custom templates and a clean Git workflow.

Obsidian Logo

Context and motivation​

My technical blog runs on Docusaurus, a static site generator that uses Markdown for content. While I could edit files directly with VS Code or any text editor, I needed a writing environment better suited for writing long articles with:

  • A dedicated writing interface: Obsidian offers focus mode and real-time Markdown preview
  • Reusable templates: To ensure consistency of Docusaurus frontmatter (YAML metadata)
  • Automatic Git synchronization: Automatic pulls every 10 minutes to fetch remote changes
  • Clear separation: Only editorial content (blog, docs, images) without Docusaurus technical files

Setup architecture​

The principle is simple: use Git sparse checkout to retrieve only content folders from the repository, and configure Obsidian with the Git plugin to synchronize changes on a dedicated branch.

Obsidian Vault (local)
├── blog/           ← Blog posts (FR)
├── docs/           ← Documentation (FR)
├── i18n/           ← Translations (EN)
├── static/         ← Images and assets
└── templates/      ← Local templates (not versioned)

↓ Git sync (branch "contenu")

Forgejo → GitHub → Cloudflare Pages

Publishing workflow:

  1. I write in Obsidian and commit manually on the contenu branch
  2. Automatic pull every 10 minutes to fetch remote changes
  3. Manual push when I want to sync with the server
  4. When the article is ready: Pull Request on Forgejo from contenu to main
  5. After merge: automatic deployment on Cloudflare Pages

Step 1: Setting up the Obsidian vault with sparse checkout​

Initial clone with sparse checkout​

Sparse checkout allows retrieving only the necessary folders without downloading the entire Docusaurus project (node_modules, build, etc.).

New-Item -ItemType Directory .\Obsidian
Set-Location .\Obsidian

git clone --no-checkout https://forgejo.tellserv.fr/Tellsanguis/blog_tech.git .

git sparse-checkout disable
git sparse-checkout init --cone
git sparse-checkout set blog docs i18n static
git read-tree -mu HEAD

git ls-files | Where-Object { $_ -notmatch '/' } | ForEach-Object { git update-index --assume-unchanged -- $_ }
git ls-files | Where-Object { $_ -notmatch '/' } | ForEach-Object { if (Test-Path $_) { Remove-Item -Force $_ -ErrorAction SilentlyContinue } }
git read-tree -mu HEAD

git checkout -b contenu
git push -u origin contenu

Command explanation:

  • git clone --no-checkout: Clones the repository without extracting files
  • git sparse-checkout set blog docs i18n static: Defines folders to retrieve
  • git ls-files commands: Mark root files as "assume-unchanged" and remove them from the working tree
  • git checkout -b contenu: Creates and switches to the working branch

Expected result: Only blog/, docs/, i18n/, static/ and .git/ folders are present.

Configuring .gitignore​

To avoid versioning Obsidian-specific files:

# Obsidian
.obsidian/
.trash/
templates/

# System files
.DS_Store
Thumbs.db

Templates are local and personal, no need to version them in the main repository.

Step 2: Installing and configuring Obsidian​

Opening the vault​

  1. Launch Obsidian
  2. Open folder as vault → Select C:\Users\Tellsanguis\Documents\Obsidian

Installing the Obsidian Git plugin​

The Obsidian Git plugin allows managing Git directly from Obsidian without using the command line.

  1. Settings (gear icon at the bottom left) → Community plugins
  2. Turn on community plugins
  3. Browse → Search for "Obsidian Git" (by Vinzent03)
  4. Install → Enable

Installing the Obsidian Git plugin

Configuring the Obsidian Git plugin​

Settings → Obsidian Git:

"Automatic" section​

Auto pull configuration

  • Auto pull interval (minutes): 10 → Fetches remote changes every 10 minutes

This configuration keeps you synchronized with changes made from other machines or by other contributors.

"Pull" section​

Pull on startup and other settings

  • Pull on startup: Enabled → Automatic pull when Obsidian starts
  • Merge strategy: Merge → Default merge strategy

"Commit author" section​

Commit author configuration

This correctly identifies the commit author in Git history.

"Commit message" section​

  • Commit message: "vault backup: {{date}}"

This syntax provides automatic commit messages with the date, for example: vault backup: 2025-12-10 14:30

Step 3: Creating templates​

Templates facilitate creating articles and documentation with the correct frontmatter format expected by Docusaurus.

Configuring the Templates plugin​

  1. Settings → Core plugins → Templates: Enable
  2. Settings → Templates:
    • Template folder location: templates
    • Date format: YYYY-MM-DD

Displaying frontmatter properties​

Properties in source documents

To see YAML properties (frontmatter) directly in the editor, select "source" in the property display settings.

Daily workflow​

Creating a new blog post​

  1. Right-click in the blog/ folder → New note
  2. Name: YYYY-MM-DD-title-slug.md (e.g., 2025-12-10-my-article.md)
  3. Insert template:
    • Ctrl+P (Command Palette)
    • Type "template"
    • Select "Templates: Insert template"
    • Choose blog-cheatsheet
  4. Edit frontmatter:
    • slug: title-slug (without date)
    • title: Full article title
    • tags: Replace with actual tags
    • date: Automatically filled by Obsidian
    • image: Path to banner (if used)
  5. Write content with real-time preview
  6. Add images in static/img/blog/YYYY-MM-DD-slug/

Git synchronization​

The Obsidian Git plugin displays a panel on the right side of the window to manage synchronization:

Git panel in Obsidian

Automatic pull:

  • Automatic pull every 10 minutes to fetch remote changes
  • Automatic pull when Obsidian starts

Manual commit and push:

  1. Check changes: The Git panel displays modified files in the "Changes" section
  2. Commit: Click the commit button at the bottom of the panel or use Ctrl+P → "Git: Commit all changes"
  3. Push: Click the push button at the bottom of the panel or use Ctrl+P → "Git: Push"

Publishing to the blog​

  1. On Forgejo: https://forgejo.tellserv.fr/Tellsanguis/blog_tech
  2. Pull Requests → New Pull Request
  3. Base branch: main / Compare branch: contenu
  4. Create Pull Request → Review content → Merge
  5. Automatic pipeline: Forgejo → GitHub mirror → Cloudflare Pages → Online publication

This workflow allows reviewing and validating content before publication, with a complete Git history of all modifications.

Conclusion​

This setup allows me to benefit from a writing environment optimized for editing while maintaining a professional Git workflow with review and complete history.

The Git panel integrated directly into Obsidian greatly facilitates commit and push management, with a clear visualization of modified files. Automatic pulls ensure I always stay synchronized with the remote repository, while maintaining total control over what I commit and when I do it (in practice, I work alone on this blog: it's mainly useful for team work to have real-time updates).

If you use Docusaurus or another Markdown-based static site generator, I highly recommend this type of setup to facilitate technical content writing!