Skip to main content
Version: 2.4.0

Docusaurus Integration

O2 supports converting Obsidian notes to Docusaurus blog posts while maintaining compatibility with Docusaurus's blog features and markdown extensions.

Project Structure​

When converting notes to Docusaurus, O2 follows this structure:

your-docusaurus-project/
├── blog/
│   └── YYYY-MM-DD/
│       ├── title.md
│       └── assets/
└── static/
    └── img/
        └── blog/
            └── YYYY-MM-DD-title/
                └── attachments
  • Blog posts are organized in date-based folders
  • Assets are stored alongside their respective posts
  • Static assets are maintained in the img directory

Features​

O2 automatically converts various Obsidian-specific markdown features to Docusaurus-compatible format:

  • Internal links ([[note]]) are converted to relative URLs
  • Alias links ([[note|alias]]) preserve the alias text
  • Heading links ([[note#heading]]) are converted to anchor links
  • Image links are updated to use Docusaurus's asset path
  • File attachments are copied to the static directory
  • Relative paths are converted to absolute URLs

Callouts​

  • Obsidian callouts are converted to Docusaurus admonitions
  • Callout types (note, warning, etc.) are preserved
  • Custom styling is maintained where possible

Footnotes​

  • Inline footnotes are preserved
  • Reference-style footnotes are maintained
  • Footnote numbering is automatically handled

Comments​

  • HTML comments are preserved
  • Obsidian-specific comments are handled appropriately

Front Matter​

  • Existing fields are preserved
  • Required Docusaurus fields are added:
    • slug
    • title
    • authors
    • tags

File Organization​

  • Posts are organized in date-based folders (YYYY-MM-DD)
  • Assets are stored alongside their posts
  • Date extraction supports various patterns:
    • Filename: YYYY-MM-DD-title.md
    • Front matter: date field
    • File creation date (fallback)

Configuration​

Required settings:

  • Absolute path to Docusaurus project
  • Default authors for blog posts

Optional settings:

  • Date extraction patterns
  • Asset organization preferences
  • Auto-archive after conversion

Usage Example​

Original Obsidian note:

---
title: My Note
tags: [obsidian, notes]
---

# My First Note

Here's an [[internal link]] and an image:
![[image.png]]

> [!note]
> This is a callout

Some text with a [^footnote].

[^footnote]: This is the footnote text.

Converted Docusaurus post:

---
slug: my-note
title: My Note
authors: [default]
tags: [obsidian, notes]
---

# My First Note

Here's a [internal link](/blog/internal-link) and an image:
![image](/img/blog/2024-03-20-my-note/image.png)

:::note
This is a callout
:::

Some text with a [^footnote].

[^footnote]: This is the footnote text.

Troubleshooting​

Common issues and solutions:

Front Matter​

  • Verify required fields are present
  • Check authors configuration
  • Validate slug generation
  • Check static directory structure
  • Verify image path configuration
  • Ensure proper permissions

Date Handling​

  • Review date extraction patterns
  • Check file naming conventions
  • Verify front matter dates

Admonition Conversion​

  • Check callout syntax
  • Verify admonition types
  • Review custom styling

Known Limitations​

  1. Asset Handling

    • Large files may need manual optimization
    • Some file types may require special handling

  2. MDX Compatibility

    • Some Obsidian features may not work in MDX
    • Custom components need manual adjustment

  3. Version Control

    • Asset versioning needs manual management
    • Consider using Git LFS for large files