Obsidian Digital Garden项目中的Permalinks配置问题解析

在Obsidian Digital Garden项目中，Permalinks（永久链接）配置不当会导致网站发布时出现路径冲突问题。本文将从技术原理和解决方案两个维度，深入剖析该问题的成因及最佳实践。

问题现象分析

当用户在多个Markdown文件中同时设置dg-home属性时，系统会生成重复的首页路径。Obsidian Digital Garden的静态站点生成器会将这些文件都编译到根目录下，导致路由冲突。典型表现为：

1. 单文件发布时工作正常
2. 多文件发布时出现路径解析异常
3. 浏览器控制台可能显示404或路由匹配错误

核心配置原理

该项目的路由系统依赖两个关键元数据属性：

1. dg-home：有且只能在一个文件中声明，用于指定站点首页
2. dg-publish：需要发布的所有文件都必须包含此属性

解决方案

1. 唯一首页声明
   检查所有Markdown文件的frontmatter，确保只有一个文件包含：

   dg-home: true
   

2. 发布控制
   需要发布的文件必须添加：

   dg-publish: true
   

3. 目录结构优化
   建议采用以下结构：

   /notes
     homepage.md      # 唯一包含dg-home的文件
     article-1.md     # 常规发布文件
     article-2.md     # 常规发布文件
   

高级配置建议

1. .eleventy.js配置
   可在配置文件中添加路径校验逻辑，当检测到多个dg-home时抛出构建错误：

   module.exports = function(eleventyConfig) {
     let homePageCount = 0;
     eleventyConfig.addCollection("gardenPages", function(collection) {
       return collection.getAll().filter(item => {
         if(item.data.dg-home) homePageCount++;
         return item.data.dg-publish;
       });
     });
     
     eleventyConfig.on('eleventy.before', () => {
       if(homePageCount > 1) {
         throw new Error(`Multiple home pages detected (${homePageCount})`);
       }
     });
   }
   

2. Frontmatter验证
   推荐使用Obsidian Linter插件自动校验frontmatter格式，防止配置错误。

总结

正确理解Obsidian Digital Garden的路由机制是解决Permalinks问题的关键。开发者应当建立严格的内容发布规范，特别是对于首页这种特殊路由的声明要保持唯一性。通过合理的项目结构和自动化校验，可以有效避免此类配置问题。