obsidian-dev-skills 1.0.0

package/obsidian-ops/references/sync-procedure.md

@@ -0,0 +1,381 @@
+<!--
+Source: Project-specific procedure
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update as sync process evolves
+Applicability: Both
+-->
+
+# Sync Procedure: Keeping .agents Up to Date
+
+**Sync Tracking**: All sync dates are tracked centrally in [sync-status.json](sync-status.json). Always update this file with the actual current date when syncing (use `Get-Date -Format "yyyy-MM-dd"` to get the date - never use placeholder dates).
+
+This document outlines the standard procedure for keeping the `.agents` directory content synchronized with the latest updates from the 6 core Obsidian repositories:
+- [Obsidian API](https://github.com/obsidianmd/obsidian-api) - Official API documentation and type definitions
+- [Obsidian Sample Plugin](https://github.com/obsidianmd/obsidian-sample-plugin) - Template plugin with best practices
+- [Obsidian Developer Docs](https://github.com/obsidianmd/obsidian-developer-docs) - Source vault for docs.obsidian.md
+- [Obsidian Plugin Docs](https://github.com/obsidianmd/obsidian-plugin-docs) - Plugin-specific documentation
+- [Obsidian Sample Theme](https://github.com/obsidianmd/obsidian-sample-theme) - Theme template (for reference patterns)
+- [ESLint Plugin](https://github.com/obsidianmd/eslint-plugin) - ESLint rules for Obsidian plugins
+
+## Prerequisites
+
+1. **Set up reference repositories** (see [ref-instructions.md](ref-instructions.md)):
+   - The 6 core Obsidian projects should be available in `.ref/` (either as symlinks to a central location or as local clones):
+     - `obsidian-api/` - API documentation
+     - `obsidian-sample-plugin/` - Sample plugin template
+     - `obsidian-developer-docs/` - Developer documentation
+     - `obsidian-plugin-docs/` - Plugin-specific docs
+     - `obsidian-sample-theme/` - Theme template
+     - `eslint-plugin/` - ESLint rules
+   - **Important**: If using symlinks (recommended), they typically point to a central location like `..\.ref\obsidian-dev` (one level up from project root) or `~/Development/.ref/obsidian-dev`
+
+## Sync Workflow
+
+**Before starting**: Get the current date for tracking (always use actual date, never placeholder):
+```powershell
+$syncDate = Get-Date -Format "yyyy-MM-dd"
+Write-Host "Sync date: $syncDate"
+```
+
+### Step 1: Determine Your .ref Setup
+
+**CRITICAL**: Before updating repos, you need to determine whether `.ref` contains symlinks or actual repos. Git operations must be performed on the **actual target location**, not on symlinks.
+
+#### Check if .ref Contains Symlinks
+
+**Windows (PowerShell)**:
+```powershell
+# Check if a specific repo is a symlink
+$item = Get-Item .ref/obsidian-api
+if ($item.LinkType -eq "Junction" -or $item.LinkType -eq "SymbolicLink") {
+    Write-Host "Symlink detected - target: $($item.Target)"
+    # Navigate to the actual target location
+    cd $item.Target
+} else {
+    Write-Host "Regular directory - can use .ref/obsidian-api directly"
+    cd .ref/obsidian-api
+}
+```
+
+**macOS/Linux**:
+```bash
+# Check if a specific repo is a symlink
+if [ -L .ref/obsidian-api ]; then
+    echo "Symlink detected - target: $(readlink .ref/obsidian-api)"
+    # Navigate to the actual target location
+    cd "$(readlink -f .ref/obsidian-api)"
+else
+    echo "Regular directory - can use .ref/obsidian-api directly"
+    cd .ref/obsidian-api
+fi
+```
+
+**Quick Check**: If `.ref` contains symlinks, they typically point to `..\.ref\obsidian-dev` (one level up from project root) or a central location like `~/Development/.ref/obsidian-dev` or `C:\Users\YourName\Development\.ref\obsidian-dev`.
+
+### Step 2: Update Reference Repositories
+
+Once you know your setup, update the repos:
+
+#### Option A: If Using Symlinks to Central Location
+
+**Windows (PowerShell)**:
+```powershell
+# First, check where symlinks point (usually ..\.ref\obsidian-dev)
+$target = (Get-Item .ref/obsidian-api).Target
+Write-Host "Symlinks point to: $target"
+
+# Navigate to central location and update all repos
+cd ..\.ref\obsidian-dev  # Adjust path if your central .ref is elsewhere
+cd obsidian-api; git pull; cd ..
+cd obsidian-sample-plugin; git pull; cd ..
+cd obsidian-developer-docs; git pull; cd ..
+cd obsidian-plugin-docs; git pull; cd ..
+cd obsidian-sample-theme; git pull; cd ..
+cd eslint-plugin; git pull; cd ..
+```
+
+**macOS/Linux**:
+```bash
+# First, check where symlinks point (usually ../.ref/obsidian-dev)
+TARGET=$(readlink -f .ref/obsidian-api | sed 's|/obsidian-api$||')
+echo "Symlinks point to: $TARGET"
+
+# Navigate to central location and update all repos
+cd "$TARGET"  # or cd ../.ref/obsidian-dev if that's your central location
+cd obsidian-api && git pull && cd ..
+cd obsidian-sample-plugin && git pull && cd ..
+cd obsidian-developer-docs && git pull && cd ..
+cd obsidian-plugin-docs && git pull && cd ..
+cd obsidian-sample-theme && git pull && cd ..
+cd eslint-plugin && git pull && cd ..
+```
+
+#### Option B: If Using Local Clones (No Symlinks)
+
+If `.ref` contains actual repos (not symlinks), update from project root:
+
+**Windows (PowerShell)**:
+```powershell
+# Always start from project root for each command
+cd C:\path\to\your\obsidian-project
+cd .ref/obsidian-api; git pull
+cd C:\path\to\your\obsidian-project
+cd .ref/obsidian-sample-plugin; git pull
+cd C:\path\to\your\obsidian-project
+cd .ref/obsidian-developer-docs; git pull
+cd C:\path\to\your\obsidian-project
+cd .ref/obsidian-plugin-docs; git pull
+cd C:\path\to\your\obsidian-project
+cd .ref/obsidian-sample-theme; git pull
+cd C:\path\to\your\obsidian-project
+cd .ref/eslint-plugin; git pull
+```
+
+**macOS/Linux**:
+```bash
+# Always start from project root for each command
+cd .ref/obsidian-api && git pull && cd ../..
+cd .ref/obsidian-sample-plugin && git pull && cd ../..
+cd .ref/obsidian-developer-docs && git pull && cd ../..
+cd .ref/obsidian-plugin-docs && git pull && cd ../..
+cd .ref/obsidian-sample-theme && git pull && cd ../..
+cd .ref/eslint-plugin && git pull && cd ../..
+```
+
+**Important**: When using local clones, always navigate back to project root between commands to avoid path accumulation errors.
+
+### Step 3: Review Changes
+
+Check what's changed in the reference repos. **Remember**: If using symlinks, navigate to the actual target location (usually `..\.ref\obsidian-dev`), not the symlink.
+
+**Windows (PowerShell)** - If using symlinks:
+```powershell
+# Navigate to central location first
+cd ..\.ref\obsidian-dev  # Adjust if your central .ref is elsewhere
+
+# Check recent commits in obsidian-api
+cd obsidian-api
+git log --oneline -10
+cd ..
+
+# Check recent commits in obsidian-sample-plugin
+cd obsidian-sample-plugin
+git log --oneline -10
+git diff HEAD~1 HEAD -- AGENTS.md  # Check if AGENTS.md changed
+cd ..
+
+# Check developer docs changes
+cd obsidian-developer-docs
+git log --oneline -10
+cd ..
+
+# Check plugin docs changes
+cd obsidian-plugin-docs
+git log --oneline -10
+cd ..
+```
+
+**Windows (PowerShell)** - If using local clones:
+```powershell
+# Always start from project root for each command
+cd C:\path\to\your\obsidian-project
+cd .ref\obsidian-api
+git log --oneline -10
+cd C:\path\to\your\obsidian-project
+cd .ref\obsidian-sample-plugin
+git log --oneline -10
+git diff HEAD~1 HEAD -- AGENTS.md
+```
+
+**macOS/Linux** - If using symlinks:
+```bash
+# Navigate to central location first
+cd ../.ref/obsidian-dev  # or cd ~/Development/.ref/obsidian-dev
+
+# Check recent commits
+cd obsidian-api && git log --oneline -10 && cd ..
+cd obsidian-sample-plugin && git log --oneline -10 && git diff HEAD~1 HEAD -- AGENTS.md && cd ..
+cd obsidian-developer-docs && git log --oneline -10 && cd ..
+cd obsidian-plugin-docs && git log --oneline -10 && cd ..
+```
+
+### Step 4: Identify Files to Update
+
+Based on the changes, identify which `.agents` files need updates:
+
+- **Sample Plugin changes** → Check these files:
+  - `environment.md` - Build tooling, npm scripts
+  - `file-conventions.md` - File structure recommendations
+  - `common-tasks.md` - Code examples
+  - `testing.md` - Installation procedures
+  - `versioning-releases.md` - Release workflow
+  - `coding-conventions.md` - TypeScript patterns
+
+- **API changes** → Check these files:
+  - `project-overview.md` - API usage patterns
+  - `commands-settings.md` - Command API changes
+  - `common-tasks.md` - API usage examples
+  - `references.md` - API documentation links
+
+- **Developer Docs changes** → Check:
+  - `security-privacy.md` - Policy updates
+  - `manifest.md` - Manifest requirements
+  - `ux-copy.md` - Style guide updates
+  - `commands-settings.md` - Command documentation
+  - `testing.md` - Testing procedures
+  - `versioning-releases.md` - Release guidelines
+  - Review `en/` directory for new or updated documentation
+
+- **Plugin Docs changes** → Check:
+  - `project-overview.md` - Plugin architecture
+  - `common-tasks.md` - Plugin-specific patterns
+  - `troubleshooting.md` - Common plugin issues
+  - Any plugin-specific best practices
+
+- **Sample Theme changes** (optional reference):
+  - `file-conventions.md` - File organization patterns
+  - `versioning-releases.md` - Release workflow similarities
+
+### Step 5: Update .agents Files
+
+For each file that needs updating:
+
+1. **Read the source material**:
+   - Compare `.ref/obsidian-sample-plugin/AGENTS.md` with current `.agents` files
+   - Review `.ref/obsidian-api/` for API documentation changes
+   - Review `.ref/obsidian-developer-docs/en/` for official documentation updates
+   - Check `.ref/obsidian-plugin-docs/` for plugin-specific guidance
+   - Optionally reference `.ref/obsidian-sample-theme/` for organizational patterns
+
+2. **Update the content**:
+   - Copy relevant sections from source
+   - Adapt to match the topic-based structure
+   - Preserve any project-specific additions
+
+3. **Update the sync status**:
+   
+   **Easy way** (recommended): Use the helper script:
+   ```bash
+   node scripts/update-sync-status.mjs "Description of what was synced"
+   ```
+   
+   **Manual way**: Edit `.agent/sync-status.json` directly:
+   ```powershell
+   # Get the current date
+   $syncDate = Get-Date -Format "yyyy-MM-dd"
+
+   # Update the central sync-status.json file
+   # Edit .agent/sync-status.json and update:
+   # - "lastFullSync" to the current date
+   # - "lastSyncSource" to describe what was synced
+   # - Update relevant source repo dates in "sourceRepos"
+   ```
+   
+   **Important**: Always use the actual current date from `Get-Date -Format "yyyy-MM-dd"`, never use placeholder dates.
+
+4. **Note**: Individual file headers still have "Last synced" dates, but the authoritative source is `.agent/sync-status.json`. When syncing, update the central file rather than individual file headers.
+
+### Step 6: Verify and Test
+
+- Review updated files for accuracy
+- Ensure links still work
+- Check that code examples are still valid
+- Verify formatting is consistent
+
+## Quick Sync Checklist
+
+- [ ] **Determine setup**: Check if `.ref` contains symlinks or actual repos
+- [ ] **If symlinks**: Identify central location (usually `..\.ref\obsidian-dev` or `~/Development/.ref/obsidian-dev`)
+- [ ] **If local clones**: Note that you must navigate from project root for each command
+- [ ] Pull latest from `obsidian-api` repo (from actual target location, not symlink)
+- [ ] Pull latest from `obsidian-sample-plugin` repo
+- [ ] Pull latest from `obsidian-developer-docs` repo
+- [ ] Pull latest from `obsidian-plugin-docs` repo
+- [ ] Pull latest from `obsidian-sample-theme` repo
+- [ ] Pull latest from `eslint-plugin` repo
+- [ ] Review `AGENTS.md` in sample plugin for changes
+- [ ] Review API documentation for breaking changes
+- [ ] Review developer docs for policy/guideline updates
+- [ ] Review plugin docs for best practices
+- [ ] Update relevant `.agent/skills/**/*.md` files
+- [ ] **Update `.agent/sync-status.json` with actual current date** (use `Get-Date -Format "yyyy-MM-dd"` - never use placeholder dates)
+- [ ] Review and commit changes
+
+## Troubleshooting
+
+### "Cannot find path" errors when running git commands
+
+**Problem**: You're trying to run git commands on a symlink, or paths are accumulating incorrectly.
+
+**Solution**:
+1. Check if `.ref` contains symlinks: `Get-Item .ref/obsidian-api | Select-Object LinkType, Target` (Windows) or `ls -la .ref/obsidian-api` (Unix)
+2. If symlinks, navigate to the **actual target location** (usually `..\.ref\obsidian-dev`) before running git commands
+3. If local clones, always start from project root for each command
+
+### "Already up to date" but you want to verify
+
+**Solution**: Use `git fetch` first to check for updates without merging:
+```bash
+git fetch
+git log HEAD..origin/main --oneline  # Shows what's new
+```
+
+### Verify Your Setup (Symlinks vs. Local Clones)
+
+**Windows**:
+```powershell
+Get-Item .ref/obsidian-api | Select-Object LinkType, Target
+# If LinkType shows "Junction" or "SymbolicLink", you're using symlinks
+# If LinkType is empty/null, it's a regular directory
+```
+
+**macOS/Linux**:
+```bash
+ls -la .ref/obsidian-api
+# If it shows "->" with a path, it's a symlink
+# If it shows "d" (directory) without "->", it's a regular directory
+```
+
+## Frequency Recommendations
+
+- **Monthly**: Review for major updates
+- **After Obsidian releases**: Check for API changes
+- **When starting new features**: Verify current best practices
+- **Before releases**: Ensure guidelines are current
+
+## Automation Ideas (Future)
+
+Consider creating a script to:
+- Automatically check for updates in reference repos
+- Compare `AGENTS.md` from sample plugin with current `.agents` structure
+- Generate a diff report of what changed
+- Remind to update "Last synced" dates
+
+## Updating Sync Status
+
+After completing a sync, update `.agent/sync-status.json`:
+
+**Easy way** (recommended): Use the helper script:
+```bash
+node scripts/update-sync-status.mjs "Description of what was synced"
+```
+
+**Manual way**: Edit the file directly:
+```powershell
+# Get actual current date (CRITICAL: never use placeholder!)
+$syncDate = Get-Date -Format "yyyy-MM-dd"
+
+# Update sync-status.json with:
+# - "lastFullSync": "$syncDate"
+# - "lastSyncSource": "Description of what was synced"
+# - Update relevant dates in "sourceRepos" section for repos that were checked/synced
+```
+
+**Critical**: Always use the actual date from `Get-Date -Format "yyyy-MM-dd"`. Never use placeholder dates like "YYYY-MM-DD" or hardcoded dates. The sync-status.json file is the authoritative source for all sync dates.
+
+## Notes
+
+- Not all changes need to be synced immediately - focus on breaking changes and new best practices
+- Some content may be project-specific and shouldn't be overwritten
+- Always review changes before committing to ensure they make sense for your project
+- **Always update sync-status.json with the actual current date** - this is the authoritative source for sync dates

package/obsidian-ops/references/testing.md

@@ -0,0 +1,17 @@
+<!--
+Source: Based on Obsidian Sample Theme
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Theme repo for updates
+-->
+
+# Testing
+
+- Manual install for testing: copy `manifest.json` and `theme.css` to:
+  ```
+  <Vault>/.obsidian/themes/<theme-name>/
+  ```
+- Reload Obsidian and select the theme in **Settings → Appearance → Themes**.
+
+**Platform testing**: Before release, test on all applicable platforms (Windows, macOS, Linux, Android, iOS). See [release-readiness.md](release-readiness.md) for the complete testing checklist.
+
+

package/obsidian-ops/references/troubleshooting.md

@@ -0,0 +1,114 @@
+<!--
+Source: Based on Obsidian community troubleshooting
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update as common issues are identified
+-->
+
+# Troubleshooting
+
+**Source**: Based on common errors from developer docs, community patterns, and best practices.
+
+- **Theme doesn't appear**: Ensure `manifest.json` and `theme.css` are at the top level of the theme folder under `<Vault>/.obsidian/themes/<theme-name>/`.
+- **Theme not applying**: Check that `manifest.json` has correct `name` field matching the folder name.
+- **CSS not loading**: Verify `theme.css` exists and is properly formatted.
+- **SCSS compilation issues**: If using SCSS, ensure build process runs and outputs `theme.css`.
+- **Mobile display issues**: Test CSS on mobile devices and check for viewport-specific styles.
+
+## AI Agent Issues
+
+### .ref Folder Not Found
+
+**Problem**: AI agent can't find `.ref` folder when searching.
+
+**Solution**:
+- The `.ref` folder is gitignored and may be hidden
+- Use `list_dir` with the project root to see hidden directories
+- Use `glob_file_search` with pattern `.ref/**` to search recursively
+- Try direct paths like `.ref/obsidian-api/README.md`
+- See [ref-instructions.md](ref-instructions.md) for detailed search strategies
+
+**For AI agents**: When user asks about `.ref`, actively search using multiple methods. Don't assume it doesn't exist if first search fails.
+
+## Common Error Messages
+
+### CSS Errors
+
+- **"Invalid property value"**: Check CSS syntax, ensure all values are properly formatted.
+- **"Unknown property"**: Verify CSS property names are correct and supported by Obsidian's rendering engine.
+- **"Selector not working"**: Check CSS selector specificity and ensure you're targeting the correct Obsidian elements.
+
+### SCSS Compilation Errors
+
+- **"File to import not found"**: Check `@import` paths are correct relative to SCSS files.
+- **"Undefined variable"**: Ensure all SCSS variables are defined before use.
+- **"Syntax error"**: Verify SCSS syntax is correct (semicolons, brackets, etc.).
+
+### Build Errors
+
+- **"Command not found"**: Ensure build tools (Grunt, npm, sass) are installed.
+- **"Build failed"**: Check build configuration files (`Gruntfile.js`, `package.json` scripts).
+- **"Output file missing"**: Verify build process completed and `theme.css` was generated.
+
+## Debugging Techniques
+
+### Browser Console
+
+Open browser console (Help → Toggle Developer Tools) to check for:
+- CSS parsing errors
+- Missing CSS variables
+- Conflicting styles
+
+### Inspect Theme CSS
+
+In browser console, inspect the theme's CSS:
+```javascript
+// Check if theme CSS is loaded
+document.querySelector('style[data-theme="your-theme-name"]')
+```
+
+### Verify CSS Variables
+
+Check that Obsidian CSS variables are being used correctly:
+```css
+/* Use Obsidian's built-in variables */
+color: var(--text-normal);
+background: var(--background-primary);
+```
+
+### Check Manifest
+
+Verify `manifest.json` has correct `name` field matching the theme folder name.
+
+## SCSS Build Issues (Detailed)
+
+### SCSS Not Compiling
+
+**Causes**:
+1. Build command not run
+2. Build tool not installed
+3. Incorrect build configuration
+
+**Solution**: 
+1. Run build command (`npx grunt build` or `npm run build`)
+2. Verify `Gruntfile.js` or `package.json` scripts are correct
+3. Check that `theme.css` is generated in root directory
+
+### SCSS Import Errors
+
+**Problem**: `@import` statements fail.
+
+**Solution**: 
+1. Check file paths are correct relative to importing file
+2. Verify all imported files exist
+3. Use relative paths: `@import "../variables.scss";`
+
+### CSS Output Issues
+
+**Problem**: Compiled CSS doesn't match expected output.
+
+**Solution**:
+1. Check SCSS source files for syntax errors
+2. Verify build process completes without errors
+3. Inspect generated `theme.css` for issues
+
+

package/obsidian-ops/references/versioning-releases.md

@@ -0,0 +1,16 @@
+<!--
+Source: Based on Obsidian Sample Theme
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Theme repo for updates
+-->
+
+# Versioning & releases
+
+**Before releasing**: Use the comprehensive [release-readiness.md](release-readiness.md) checklist to verify your theme is ready for release.
+
+- Bump `version` in `manifest.json` (SemVer).
+- Create a GitHub release whose tag exactly matches `manifest.json`'s `version`. Do not use a leading `v`.
+- Attach `manifest.json` and `theme.css` to the release as individual assets.
+- After the initial release, follow the process to add/update your theme in the community catalog as required.
+
+

package/obsidian-ref/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: obsidian-ref
+description: Technical references, manifest rules, file formats, and UX guidelines for Obsidian. Load when checking API details, manifest requirements, or UI/UX standards.
+---
+
+# Obsidian Reference Skill
+
+This skill provides comprehensive technical references and standards for the Obsidian ecosystem.
+
+## Purpose
+
+To provide a central source of truth for API usage, file formats, and design standards.
+
+## When to Use
+
+Load this skill when:
+- Verifying `manifest.json` requirements.
+- Checking Obsidian API details or documentation.
+- Working with Obsidian-specific file formats (Markdown, Canvas).
+- Reviewing UI text or UX patterns for consistency.
+
+## Core Rules
+
+- **API Authority**: The `obsidian.d.ts` file in the reference materials is the authoritative source for API details.
+- **Terminology Consistency**: Follow the "properties" and "Markdown" naming conventions strictly.
+- **Mobile First**: Consider mobile compatibility for all UI and file-handling features.
+
+## Bundled Resources
+
+- `references/manifest.md`: Detailed rules for `manifest.json`.
+- `references/obsidian-file-formats.md`: Specifications for Markdown, Properties, and Canvas.
+- `references/ux-copy.md`: UI text conventions and UX best practices.
+- `references/references.md`: External links and primary source locations.
+- `references/mobile.md`: Considerations for mobile compatibility.
+- `references/performance.md`: Best practices for performance.

package/obsidian-ref/references/environment.md

@@ -0,0 +1,52 @@
+<!--
+Source: Based on Obsidian Sample Theme
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Theme repo for updates
+-->
+
+# Environment & tooling
+
+- **Optional**: Node.js and npm if using SCSS/Sass preprocessors or build tools.
+- **Simple themes**: Can be developed with just CSS and `manifest.json` (no build tools required).
+- **SCSS themes**: Use Sass/SCSS compiler (e.g., `sass`, `node-sass`, or build tools like Vite).
+- No TypeScript or bundler required for basic themes.
+
+## Simple Theme Setup
+
+No build tools needed - just edit `theme.css` directly.
+
+## SCSS Theme Setup
+
+```bash
+npm install -D sass
+npm run build  # Compile SCSS to CSS
+```
+
+## Theme Build Tools (Optional)
+
+Simple themes with just CSS don't need build tools. More complex themes might use Grunt, npm scripts, or other build tools for tasks like SCSS compilation, minification, or preprocessing:
+
+```bash
+# For themes using Grunt
+npx grunt build
+
+# For themes using npm scripts
+npm run build
+```
+
+Only use build commands if your theme has a `Gruntfile.js`, `package.json` with build scripts, or other build configuration files.
+
+## Linting (Optional)
+
+- Use `stylelint` for CSS/SCSS linting: `npm install -D stylelint`
+- Configure stylelint for Obsidian theme conventions
+- **Quick Setup**: Run `node scripts/setup-stylelint.mjs` to set up Stylelint with helpful success messages
+- **Run Stylelint**:
+  ```bash
+  npm run lint        # Uses lint-wrapper.mjs for helpful success messages
+  npm run lint:fix    # Auto-fix issues where possible
+  ```
+
+**Note**: The setup script automatically creates `scripts/lint-wrapper.mjs` which adds helpful success messages when linting passes. The wrapper is included in the template and copied during setup.
+
+

package/obsidian-ref/references/file-conventions.md

@@ -0,0 +1,65 @@
+<!--
+Source: Based on Obsidian Sample Theme
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check Obsidian Sample Theme repo for updates
+-->
+
+# File & folder conventions
+
+- **Organize CSS/SCSS into logical files**: Split styles into separate files for maintainability.
+- **Theme structure patterns**:
+  - **Simple CSS theme** (recommended for simple themes): `theme.css` in project root, no build step required
+  - **Complex theme with build tools** (for themes using SCSS, Grunt, etc.): `src/scss/` directory with SCSS source files that compile to `theme.css`
+  - **CRITICAL**: Never have both `theme.css` as source AND `src/scss/` - choose one pattern
+
+### Simple CSS Theme Structure
+
+**Recommended for simple themes** (like the sample theme template):
+```
+theme.css          # ✅ Source CSS file (edit directly)
+manifest.json
+package.json
+```
+
+- No build step required - just edit `theme.css` directly
+- Changes take effect when Obsidian reloads the theme
+- Perfect for learning and simple themes
+
+### Complex Theme Structure (SCSS + Build Tools)
+
+**For themes using SCSS, Grunt, npm scripts, or other build tools**:
+```
+src/
+  scss/            # ✅ SCSS source files
+    index.scss
+    variables.scss
+    components/
+  css/            # Compiled CSS (intermediate, not committed)
+    main.css
+theme.css         # ✅ Final compiled output (committed)
+Gruntfile.js      # Build configuration (if using Grunt)
+manifest.json
+package.json
+```
+
+- Source files in `src/scss/` are compiled to `theme.css`
+- Build tools (Grunt, npm scripts, etc.) handle compilation
+- Run build command after making changes (see [build-workflow.md](build-workflow.md))
+- **Example**: The `obsidian-oxygen` theme uses this pattern with Grunt
+
+### Wrong Structure (Common Mistakes)
+
+```
+theme.css         # ❌ DON'T have both
+src/
+  scss/          # ❌ This causes confusion about which is the source
+    index.scss
+```
+
+**Best practice**: Choose one pattern and stick with it. Simple themes should use `theme.css` directly. Complex themes should use `src/scss/` and compile to `theme.css`.
+
+- **Do not commit build artifacts**: Never commit `node_modules/`, intermediate compiled CSS files (like `src/css/main.css`), or other generated files. Only commit `theme.css` (the final output).
+- Keep themes lightweight. Avoid complex build processes unless necessary.
+- Release artifacts: `manifest.json` and `theme.css` must be at the top level of the theme folder in the vault.
+
+