Starsoup Docs

Appearance

Obsidian 文檔規則 ​

生效日期: 2026-04-01 適用範圍: starsoup/✨討論稿/ 及所有同步到 starsoup-docs 的 Markdown 文檔 目標: 保留 Obsidian 的編輯習慣，同時保證 VitePress 可以穩定構建與部署

1. 摘要 ​

  • 已確認需要規範化的問題類型：
    • 指向非頁面資產的 wiki link
    • 指向站外或未同步資料的 wiki link
    • 會被 Markdown 或 URL 解析破壞的附件檔名與圖片路徑
    • 容易被 VitePress 當成模板編譯的裸露 Vue / HTML / n8n 表達式

本次實測以 starsoup 全量內容同步到 starsoup-docs 後，可完成完整 VitePress build；目前重點是保持寫法持續符合這份規則，避免後續新增內容再引入不兼容語法。

2. 允許的標準寫法 ​

2.1 內部頁面連結 ​

  • 同站內 Markdown 頁面優先使用 wiki link：
    • [[頁面名]]
    • [[子目錄/頁面名|顯示文字]]
  • 在 Markdown 表格中使用 alias 時，分隔符寫成 \|：
    • [[cis/Index\|CIS]]

2.2 圖片引用 ​

  • 頁面圖片統一放在當前文檔同層的 Attachments/ 目錄。
  • 圖片引用統一使用 Obsidian embed：
    • ![[image.png]]
  • 不要手動寫成 ![](Attachments/image.png)，讓轉換器自動補路徑。

2.3 Callout 與標籤 ​

  • Callout 使用 Obsidian 原生格式：
md
::: tip 標題
內容
:::
  • 行內標籤可以寫成：#plan、#guide、#architecture

2.4 代碼、命令與 JSON 範例 ​

  • 所有命令、JSON、Vue、n8n 表達式、Shell 腳本，一律放在 fenced code block 中；不要把雙大括號模板直接寫在正文、清單、表格 cell 或 inline code 裡。
  • 目前站點已承接以下常用 code fence 語言：bash、json、javascript、python、text、env、gitignore。
  • 推薦寫法：
md
```bash
JOB_ID={{ $json.jobId }}
```

如果正文需要提到某個 n8n 表達式，先用一句自然語言描述，再把實際內容放到獨立 code fence。

3. 禁止的寫法 ​

3.1 不要用 wiki link 指向非頁面資產 ​

  • 禁止：[[Attachments]]
  • 正確：直接描述附件目錄用途，或在頁面中使用 ![[檔名.png]]

3.2 不要用 wiki link 指向未同步到本站的文件 ​

  • 禁止：[[../其他工作區文件]]
  • 禁止：[[../../01-Tech-Tutorials/...]]
  • 正確：寫成純文字說明，或改成確定可訪問的標準 Markdown 外部連結

3.3 不要把 HTML / Vue / n8n 表達式裸露在正文裡 ​

  • 禁止直接在正文裸寫：
    • <template>
    • <script setup>
    • <style>
    • n8n 雙大括號模板
    • v-if="..."
    • @click="..."
  • 以上內容只能出現在 fenced code block 中。

3.4 不要用 wiki link 指向 .html 靜態文件 ​

  • 禁止：[[crystal_erp_new_roadmap|Roadmap]]
  • 正確：[Roadmap](./crystal_erp_new_roadmap.html)

4. 命名與結構規則 ​

  • 項目總覽頁保持在各自目錄中，名稱可沿用現有 Obsidian 習慣。
  • 文檔應盡量放在明確的子目錄下，例如：
    • cis/
    • sip/
    • script-to-video/
    • pixel-web-property/
    • starsoup規則/
  • 圖片、SVG、靜態 HTML 等非 Markdown 資產，不放到站點根部，放回對應主題目錄附近。

5. 發布前自查清單 ​

  • 這個頁面的內部連結是否都指向已同步到站點的 Markdown 頁面？
  • 所有圖片是否都放在同層 Attachments/ 目錄？
  • 所有 n8n / Vue 模板語法、<script setup>、Shell 命令是否都在 fenced code block 中？
  • 是否誤用了 [[Attachments]]、[[../...]] 這類不能部署的 wiki link？
  • 非 Markdown 靜態檔是否已改為標準 Markdown 連結？

6. 規則目的 ​

這套規則的核心不是限制 Obsidian 寫作，而是讓 starsoup-docs 可以直接吃下 starsoup 目錄內容，不需要每次部署前手工修文檔。