bot_vault

Symlink Your Content in Astro for Better Portability

3 min read

Summary

EN: Elio Struyf describes a pattern for keeping content (e.g., blog posts) in a separate git repository and linking it into an Astro site via a git submodule + filesystem symlink. The key technical challenge: Vite (Astro’s bundler) does not follow symlinks by default, causing build failures. The fix is adding resolve: { preserveSymlinks: true } to astro.config.mjs. This pattern enables content portability across multiple frontends sharing the same source content.

ZH: Elio Struyf 描述一種將內容（如部落格文章）存放於獨立 git 倉庫並透過 git submodule + 符號連結引入 Astro 網站的模式。關鍵技術挑戰：Vite（Astro 的打包器）預設不追蹤符號連結，導致建置失敗。修復方案是在 astro.config.mjs 中加入 resolve: { preserveSymlinks: true }。此模式可讓多個前端共享同一份內容來源。

Key Points

  • Pattern: content repo as git submodule → symlink into ./src/content/ → Astro reads it as local content
  • Problem: Vite’s module resolver doesn’t follow symlinks by default → build errors when importing symlinked files
  • Fix: vite: { resolve: { preserveSymlinks: true } } in astro.config.mjs
  • Use case: same markdown content used by multiple Astro sites, or content managed by non-developers in a separate repo
  • Git submodule keeps content versioned independently from site design/code

Insights

  • The preserveSymlinks option is a non-obvious configuration that’s hard to discover without this article — a good example of the kind of “tribal knowledge” that gets clipped for future reference
  • Separating content from presentation is a good architectural pattern for content-heavy sites; it enables independent deployment of content updates without touching site code
  • Git submodules are famously tricky — this pattern inherits their complexity (manual git submodule update, initialization steps)

Connections

  • This vault itself uses a similar pattern: Obsidian notes (content) are managed separately from analysis scripts (code)
  • Connects to the systems thinking article: content portability across a developer portal is exactly the kind of systemic concern Tom Johnson discusses
  • The git LFS architecture note covers the complementary challenge: large binaries in git

Raw Excerpt

“After symlinking your content directory, you’ll hit a Vite error about resolving modules through symlinks. The fix is one line in your Astro config: resolve: { preserveSymlinks: true }. Without it, Vite resolves symlinks to their real path, breaking relative imports.”

Graph View

Backlinks