Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- # Obsidian Sample Plugin Plus Cursor Prompt for Upgrading Existing Plugin Project
- ## Objective
- Analyze this Obsidian plugin project and perform the following tasks:
- 1. Add UI Tweaker plugin as a reference in the `.ref` folder (via instructions from AGENTS.md and the .agents files)
- 2. Create a settings compatibility utility for backward-compatible SettingGroup usage
- 3. Update the settings tab implementation to use SettingGroup with version checking
- 4. Update `AGENTS.md` with comprehensive project-specific details derived from the codebase and README
- ## Task 1: Add UI Tweaker to .ref Folder
- **Location**: `github.com/davidvkimball/obsidian-ui-tweaker`
- **Instructions**:
- 1. Check if `.ref` folder exists in the project root. If not, it will be created.
- 2. Create a symlink to the remote repository (`https:github.com/davidvkimball/obsidian-ui-tweaker.git`) after cloning it to the central `.ref/obsidian-dev/` folder as the `/obsidian-ui-tweaker` subfolder
- 3. Verify the symlink works by listing the directory or reading a file from it
- ## Task 2: Create Settings Compatibility Utility
- **File to create**: `src/utils/settings-compat.ts`
- **Instructions**:
- 1. Create the `src/utils/` directory if it doesn't exist
- 2. Create `settings-compat.ts` based on the pattern from UI Tweaker (`.ref/plugins/obsidian-ui-tweaker/src/utils/settings-compat.ts`)
- 3. The utility should:
- - Use `requireApiVersion('1.11.0')` to check if `SettingGroup` is available
- - Export a `createSettingsGroup()` function that:
- - Takes `containerEl: HTMLElement` and optional `heading?: string`
- - Returns a `SettingsContainer` interface with an `addSetting()` method
- - Uses `SettingGroup` if available (API 1.11.0+), otherwise falls back to manual heading creation
- - Export the `SettingsContainer` interface
- 4. Follow the exact pattern from UI Tweaker, including proper TypeScript types and error handling
- ## Task 3: Update Settings Tab Implementation
- **File to update**: `src/ui/settings-tab.ts` (or wherever the settings tab class is located)
- **Instructions**:
- 1. Import the compatibility utility:
- - Check the actual location of the settings tab file and use the appropriate import path
- - Example: `import { createSettingsGroup, SettingsContainer } from '../utils/settings-compat';`
- 2. Update the `display()` method to use `createSettingsGroup()`:
- - **First group**: Use `createSettingsGroup(containerEl)` with NO heading (like UI Tweaker's first group)
- - If additional settings naturally group together, create additional groups with headings using `createSettingsGroup(containerEl, 'Group Name')`
- - **Important**: Only create groups if they make sense naturally. Don't force groupings if the current single setting doesn't warrant it.
- 3. Replace the existing `new Setting(containerEl)` pattern with `group.addSetting((setting) => { ... })`
- 4. Maintain all existing functionality - only change the grouping mechanism
- **CRITICAL: DOM Structure and Spacing**
- ⚠️ **DO NOT create divs directly on `containerEl` outside of SettingGroup structure!**
- - **Problem**: Creating divs directly on `containerEl` (e.g., `containerEl.createDiv()`) outside of a SettingGroup breaks spacing and creates visual artifacts
- - **Solution**: All content must go through `group.addSetting()` to maintain proper spacing
- - **Exception**: If you need a custom container, add it as a setting within the group (see "Custom Containers" below)
- **Example pattern** (from UI Tweaker):
- ```typescript
- // First group (no heading)
- const generalGroup = createSettingsGroup(containerEl);
- generalGroup.addSetting((setting) => {
- setting
- .setName('Setting #1')
- .setDesc('It\'s a secret')
- .addText(text => text
- .setPlaceholder('Enter your secret')
- .setValue(this.plugin.settings.mySetting)
- .onChange(async (value) => {
- this.plugin.settings.mySetting = value;
- await this.plugin.saveSettings();
- }));
- });
- // Later groups (with headings) - only if needed
- const advancedGroup = createSettingsGroup(containerEl, 'Advanced');
- advancedGroup.addSetting((setting) => {
- // ... settings
- });
- ```
- **Conditional Visibility**
- - **DO**: Apply visibility classes directly to `setting.settingEl`:
- ```typescript
- setting.settingEl.classList.toggle("visible-class", condition);
- setting.settingEl.classList.toggle("hidden-class", !condition);
- ```
- - **DON'T**: Create separate containers on `containerEl` for conditional visibility - this breaks spacing
- - **DON'T**: Move setting elements out of their group - keep them within the group structure
- **Custom Containers (if needed)**
- If you absolutely need a custom container (e.g., for dynamically rendered content):
- 1. Add it as a setting within the group:
- ```typescript
- const contentGroup = createSettingsGroup(containerEl, "Content");
- contentGroup.addSetting((setting) => {
- // Hide the setting's default UI elements
- const nameEl = setting.settingEl.querySelector('.setting-item-name');
- const descEl = setting.settingEl.querySelector('.setting-item-description');
- const controlEl = setting.settingEl.querySelector('.setting-item-control');
- if (nameEl) (nameEl as HTMLElement).style.display = "none";
- if (descEl) (descEl as HTMLElement).style.display = "none";
- if (controlEl) (controlEl as HTMLElement).style.display = "none";
- // Remove border to make it seamless
- setting.settingEl.style.borderTop = "none";
- setting.settingEl.style.paddingTop = "0";
- setting.settingEl.style.paddingBottom = "0";
- // Add your container inside the setting element
- this.customContainer = setting.settingEl.createDiv({ cls: "custom-container" });
- });
- ```
- 2. **Never** create containers directly on `containerEl` outside of groups - this breaks spacing
- **Multi-line Descriptions**
- - Use `DocumentFragment` for multi-line descriptions:
- ```typescript
- const descFragment = document.createDocumentFragment();
- descFragment.createEl("div", { text: "First line of description." });
- descFragment.createEl("div", { text: "Second line of description." });
- setting.setDesc(descFragment);
- ```
- - **Don't** use `\n` in strings - it won't render as line breaks
- **Removing Legacy Containers**
- - If you find empty containers created directly on `containerEl` (e.g., for backward compatibility), remove them
- - These containers break SettingGroup spacing even if they're empty
- - Conditional visibility should be handled on setting elements themselves, not via separate containers
- ## Task 4: Update AGENTS.md with Project Context
- **File to update**: `AGENTS.md`
- **Instructions**: Fill in the placeholder sections in the "Project Context" area with information derived from:
- 1. **Project Overview**:
- - Read `README.md` to understand what this plugin does
- - Provide a clear, concise description of the plugin's purpose and functionality
- - Note any unique features or architectural decisions
- 2. **Important Project-Specific Details**:
- - Project Type: Plugin, theme, or template
- - Purpose: What problem does this solve?
- - Status: Production, beta, or template
- - Key Features: List main features
- - Architecture: File structure and organization patterns
- 3. **Maintenance Tasks**:
- - List ongoing maintenance requirements
- - Note any dependencies that need regular updates
- - Mention any sync requirements for reference materials
- 4. **Project-Specific Conventions**:
- - Code organization patterns
- - Naming conventions
- - Settings structure
- - Any project-specific patterns
- 5. **Project-Specific References**:
- - Add entries for any reference projects (like UI Tweaker)
- - Format: `.ref/plugins/plugin-name/` - Brief description of why it's referenced
- - Note: The 6 core Obsidian projects are always relevant (don't list them here)
- 6. **Overrides (Optional)**:
- - List any project-specific overrides to general `.agents` guidance
- - If none, state "None currently. This project follows the general `.agents` guidance."
- 7. **Key Files and Their Purposes**:
- - List important files and what they do
- - Include the settings compatibility utility if created
- - Note any unusual file structures
- 8. **Development Notes**:
- - Any important implementation details
- - Reference patterns used (e.g., SettingGroup implementation)
- - Notes about backward compatibility
- - Any gotchas or important considerations
- ## Important Guidelines
- 1. **SettingsGroup Pattern**:
- - First group: NO heading (use `createSettingsGroup(containerEl)`) - *unless* one already exists
- - Later groups (if they exist): WITH headings (use `createSettingsGroup(containerEl, 'Group Name')`)
- - Only create groups if settings naturally belong together
- - Don't force category names if they don't exist naturally
- 2. **DOM Structure Rules**:
- - **NEVER** create divs directly on `containerEl` outside of SettingGroup structure
- - All content must go through `group.addSetting()` to maintain proper spacing
- - SettingGroup automatically handles spacing between groups - don't add manual spacers
- - If you need custom containers, add them as settings within groups (see "Custom Containers" above)
- 3. **Version Checking**:
- - Always use `requireApiVersion('1.11.0')` to check for SettingGroup support
- - The compatibility utility handles fallback for older Obsidian versions
- - This allows the plugin to work on both old and new Obsidian versions
- 4. **Code Quality**:
- - Maintain existing functionality - only change the grouping mechanism
- - Follow TypeScript best practices
- - Use proper error handling
- - Match the code style of the existing codebase
- - Remove legacy/empty containers that break spacing
- 5. **Reference Implementation**:
- - **Study UI Tweaker carefully** - it demonstrates the correct pattern
- - UI Tweaker only uses `addSetting()` - it never creates divs directly on `containerEl`
- - Follow UI Tweaker's exact structure for spacing and grouping
- 6. **Documentation**:
- - Be thorough in AGENTS.md - derive information from README.md and codebase analysis
- - Use clear, descriptive language
- - Follow the existing format and structure
- ## Common Pitfalls to Avoid
- 1. **Creating containers outside groups**: This breaks spacing. Always use `addSetting()`.
- 2. **Empty legacy containers**: Remove any empty containers created for "backward compatibility" - they break spacing even if empty.
- 3. **Moving settings out of groups**: Keep all settings within their group structure for proper spacing.
- 4. **Manual spacing**: Don't add spacer divs - SettingGroup handles spacing automatically.
- 5. **Using `\n` for line breaks**: Use `DocumentFragment` instead for multi-line descriptions.
- 6. **Conditional visibility containers**: Apply visibility classes to `setting.settingEl`, not separate containers.
- ## Verification Steps
- After completing all tasks:
- 1. Verify the symlink to UI Tweaker works: `list_dir .ref/plugins/obsidian-ui-tweaker`
- 2. Verify the settings-compat.ts file was created correctly
- 3. Verify the settings tab imports and uses the compatibility utility
- 4. Verify AGENTS.md has all sections filled in with relevant information
- 5. Check that the code compiles: `npm run build` (or `npm run dev`)
- 6. Verify no linter errors: `npm run lint`
- 7. **Visual check**: Open settings and verify:
- - Proper spacing between groups
- - No broken/empty settings blocks
- - No crowded spacing between sections
- - Conditional visibility works correctly
- ## Notes
- - The UI Tweaker plugin serves as a reference implementation for SettingsGroup usage
- - The first group in UI Tweaker (auto-hide elements) has no heading - follow this pattern
- - Only create additional groups if settings naturally group together - don't force it
- - The compatibility utility ensures the plugin works on both Obsidian 1.11.0+ and older versions
- - **Key insight**: SettingGroup manages its own DOM structure and spacing - work within it, not around it
Advertisement