Skip to content

Obsidian-VuePress interoperability

Obsidian-VuePress interoperability refers to the capability of using [[Obsidian]] as an authoring environment for content intended to be deployed as a static site via [[VuePress]] (specifically using themes like vuepress-theme-reco). This workflow combines the note-taking flexibility of Obsidian with the blogging features of VuePress.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Core Configuration

The core of this integration involves setting up VuePress with a compatible theme and configuring the build environment. A common approach uses the vuepress-theme-reco theme, initialized via the @vuepress-reco/theme-cli.^[600-developer-blog-vuepress-blog-vuepress-init.md]

The config.js file defines essential settings such as the blog title, description, author details, and navigation structure.^[600-developer-blog-vuepress-blog-vuepress-init.md] It also enables specific blog configurations, friend links, and search functionality (e.g., searchMaxSuggestions: 10).^[600-developer-blog-vuepress-blog-vuepress-init.md] Markdown options like line numbers can also be enabled within this configuration.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Deployment Automation

To streamline the publishing process, a GitHub Action can be configured to automatically deploy the site.^[600-developer-blog-vuepress-blog-vuepress-init.md] This workflow is typically triggered by a push to the main branch and involves:

  1. Checking out: Fetching the full git history (using fetch-depth: 0) to ensure "last updated" timestamps are accurate.^[600-developer-blog-vuepress-blog-vuepress-init.md]
  2. Building: Cleaning the public directory, installing dependencies, and running the build script (e.g., npm run build).^[600-developer-blog-vuepress-blog-vuepress-init.md]
  3. Deploying: Using a dedicated action (like jenkey2011/vuepress-deploy) to push the build artifact to the target repository and branch.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Path and Image Management

Ensuring that links and media work correctly across both editors is a critical aspect of interoperability. VuePress imposes strict naming and formatting requirements that differ from Obsidian's default behavior.

Naming Constraints

File paths in the project cannot contain Chinese characters, as this can cause build failures or broken links in the static site.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Relative Paths for Images

To ensure images display correctly in the deployed VuePress site, image links must use relative paths rather than absolute paths.^[600-developer-blog-vuepress-blog-vuepress-init.md] Users may need to rely on Obsidian plugins—such as obsidian-consistent-attachments-and-links—to automate the enforcement of relative linking.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Using such plugins often requires disabling certain default Obsidian attachment settings to prevent conflicts in path generation.^[600-developer-blog-vuepress-blog-vuepress-init.md]

Sources

^[600-developer-blog-vuepress-blog-vuepress-init.md]