AGENTS

Repository Guidelines

This repository is an Obsidian-based digital garden. Notes are Markdown with YAML frontmatter, organized using Zettelkasten/PARA. Publishing is controlled by the publish: true flag and automated by a Python script.

Project Structure & Module Organization

• Notes: 🍀 花园导览/, 📥 Inbox/, Atlas/, Cards/, Calendar/, Extras/, Sources/, Spaces/.
• Script: publish_by_frontmatter.py at the repo root.
• Metadata: YAML frontmatter per note; backlinks via [[...]]; tags via #标签.

Build, Test, and Development Commands

• Run publish: python publish_by_frontmatter.py — selects notes with publish: true, copies to the publish repo, and performs Git actions.
• Configure inside the script: VAULT_PATH, SHOWCASE_PATH, FORCE_INCLUDE_DIRS.
• Link check: in Obsidian, use “检查失效链接” to validate backlinks before publishing.

Coding Style & Naming Conventions

• Markdown: Chinese prose; English for technical terms. Headings # → ####. Use [[双链]], #标签, atomic notes, and MOCs. Emoji prefixes are allowed (e.g., 🧰, 📂). Frontmatter fields include publish, title, date created, date modified, tags.
• Python: Follow PEP 8, 4-space indent, descriptive names. Keep configuration constants together and avoid hard-coding secrets.

Testing Guidelines

• Publishing: (1) ensure publish: true is set, (2) run the script, (3) confirm sensitive files are excluded, (4) verify Git actions succeed and only intended files appear in the publish repo.
• Links: use Obsidian’s “检查失效链接”; spot-check external URLs in edited notes.

Commit & Pull Request Guidelines

• Commits: imperative mood and focused scope. Examples: Cards: add MOC for AI notes, script: filter sensitive files.
• PRs: clear description, linked issues, before/after screenshots for MOCs/Canvas, and notes on any script or config changes.

Security & Configuration Tips

• Keep personal data and keys out of notes; .gitignore should exclude sensitive artifacts.
• The publish script filters sensitive files, but always review changes before pushing.