davidvkimball

Obsidian Sample Plugin Plus Cursor Prompt for Upgrading Existing Plugin Project

Dec 19th, 2025
226
0
Never
8
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 11.92 KB | Software | 0 0
  1. # Obsidian Sample Plugin Plus Cursor Prompt for Upgrading Existing Plugin Project
  2.  
  3. ## Objective
  4.  
  5. Analyze this Obsidian plugin project and perform the following tasks:
  6.  
  7. 1. Add UI Tweaker plugin as a reference in the `.ref` folder (via instructions from AGENTS.md and the .agents files)
  8. 2. Create a settings compatibility utility for backward-compatible SettingGroup usage
  9. 3. Update the settings tab implementation to use SettingGroup with version checking
  10. 4. Update `AGENTS.md` with comprehensive project-specific details derived from the codebase and README
  11.  
  12. ## Task 1: Add UI Tweaker to .ref Folder
  13.  
  14. **Location**: `github.com/davidvkimball/obsidian-ui-tweaker`
  15.  
  16. **Instructions**:
  17. 1. Check if `.ref` folder exists in the project root. If not, it will be created.
  18. 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
  19. 3. Verify the symlink works by listing the directory or reading a file from it
  20.  
  21. ## Task 2: Create Settings Compatibility Utility
  22.  
  23. **File to create**: `src/utils/settings-compat.ts`
  24.  
  25. **Instructions**:
  26. 1. Create the `src/utils/` directory if it doesn't exist
  27. 2. Create `settings-compat.ts` based on the pattern from UI Tweaker (`.ref/plugins/obsidian-ui-tweaker/src/utils/settings-compat.ts`)
  28. 3. The utility should:
  29. - Use `requireApiVersion('1.11.0')` to check if `SettingGroup` is available
  30. - Export a `createSettingsGroup()` function that:
  31. - Takes `containerEl: HTMLElement` and optional `heading?: string`
  32. - Returns a `SettingsContainer` interface with an `addSetting()` method
  33. - Uses `SettingGroup` if available (API 1.11.0+), otherwise falls back to manual heading creation
  34. - Export the `SettingsContainer` interface
  35. 4. Follow the exact pattern from UI Tweaker, including proper TypeScript types and error handling
  36.  
  37. ## Task 3: Update Settings Tab Implementation
  38.  
  39. **File to update**: `src/ui/settings-tab.ts` (or wherever the settings tab class is located)
  40.  
  41. **Instructions**:
  42. 1. Import the compatibility utility:
  43. - Check the actual location of the settings tab file and use the appropriate import path
  44. - Example: `import { createSettingsGroup, SettingsContainer } from '../utils/settings-compat';`
  45. 2. Update the `display()` method to use `createSettingsGroup()`:
  46. - **First group**: Use `createSettingsGroup(containerEl)` with NO heading (like UI Tweaker's first group)
  47. - If additional settings naturally group together, create additional groups with headings using `createSettingsGroup(containerEl, 'Group Name')`
  48. - **Important**: Only create groups if they make sense naturally. Don't force groupings if the current single setting doesn't warrant it.
  49. 3. Replace the existing `new Setting(containerEl)` pattern with `group.addSetting((setting) => { ... })`
  50. 4. Maintain all existing functionality - only change the grouping mechanism
  51.  
  52. **CRITICAL: DOM Structure and Spacing**
  53.  
  54. ⚠️ **DO NOT create divs directly on `containerEl` outside of SettingGroup structure!**
  55.  
  56. - **Problem**: Creating divs directly on `containerEl` (e.g., `containerEl.createDiv()`) outside of a SettingGroup breaks spacing and creates visual artifacts
  57. - **Solution**: All content must go through `group.addSetting()` to maintain proper spacing
  58. - **Exception**: If you need a custom container, add it as a setting within the group (see "Custom Containers" below)
  59.  
  60. **Example pattern** (from UI Tweaker):
  61. ```typescript
  62. // First group (no heading)
  63. const generalGroup = createSettingsGroup(containerEl);
  64. generalGroup.addSetting((setting) => {
  65. setting
  66. .setName('Setting #1')
  67. .setDesc('It\'s a secret')
  68. .addText(text => text
  69. .setPlaceholder('Enter your secret')
  70. .setValue(this.plugin.settings.mySetting)
  71. .onChange(async (value) => {
  72. this.plugin.settings.mySetting = value;
  73. await this.plugin.saveSettings();
  74. }));
  75. });
  76.  
  77. // Later groups (with headings) - only if needed
  78. const advancedGroup = createSettingsGroup(containerEl, 'Advanced');
  79. advancedGroup.addSetting((setting) => {
  80. // ... settings
  81. });
  82. ```
  83.  
  84. **Conditional Visibility**
  85.  
  86. - **DO**: Apply visibility classes directly to `setting.settingEl`:
  87. ```typescript
  88. setting.settingEl.classList.toggle("visible-class", condition);
  89. setting.settingEl.classList.toggle("hidden-class", !condition);
  90. ```
  91. - **DON'T**: Create separate containers on `containerEl` for conditional visibility - this breaks spacing
  92. - **DON'T**: Move setting elements out of their group - keep them within the group structure
  93.  
  94. **Custom Containers (if needed)**
  95.  
  96. If you absolutely need a custom container (e.g., for dynamically rendered content):
  97.  
  98. 1. Add it as a setting within the group:
  99. ```typescript
  100. const contentGroup = createSettingsGroup(containerEl, "Content");
  101. contentGroup.addSetting((setting) => {
  102. // Hide the setting's default UI elements
  103. const nameEl = setting.settingEl.querySelector('.setting-item-name');
  104. const descEl = setting.settingEl.querySelector('.setting-item-description');
  105. const controlEl = setting.settingEl.querySelector('.setting-item-control');
  106. if (nameEl) (nameEl as HTMLElement).style.display = "none";
  107. if (descEl) (descEl as HTMLElement).style.display = "none";
  108. if (controlEl) (controlEl as HTMLElement).style.display = "none";
  109. // Remove border to make it seamless
  110. setting.settingEl.style.borderTop = "none";
  111. setting.settingEl.style.paddingTop = "0";
  112. setting.settingEl.style.paddingBottom = "0";
  113. // Add your container inside the setting element
  114. this.customContainer = setting.settingEl.createDiv({ cls: "custom-container" });
  115. });
  116. ```
  117.  
  118. 2. **Never** create containers directly on `containerEl` outside of groups - this breaks spacing
  119.  
  120. **Multi-line Descriptions**
  121.  
  122. - Use `DocumentFragment` for multi-line descriptions:
  123. ```typescript
  124. const descFragment = document.createDocumentFragment();
  125. descFragment.createEl("div", { text: "First line of description." });
  126. descFragment.createEl("div", { text: "Second line of description." });
  127. setting.setDesc(descFragment);
  128. ```
  129. - **Don't** use `\n` in strings - it won't render as line breaks
  130.  
  131. **Removing Legacy Containers**
  132.  
  133. - If you find empty containers created directly on `containerEl` (e.g., for backward compatibility), remove them
  134. - These containers break SettingGroup spacing even if they're empty
  135. - Conditional visibility should be handled on setting elements themselves, not via separate containers
  136.  
  137. ## Task 4: Update AGENTS.md with Project Context
  138.  
  139. **File to update**: `AGENTS.md`
  140.  
  141. **Instructions**: Fill in the placeholder sections in the "Project Context" area with information derived from:
  142.  
  143. 1. **Project Overview**:
  144. - Read `README.md` to understand what this plugin does
  145. - Provide a clear, concise description of the plugin's purpose and functionality
  146. - Note any unique features or architectural decisions
  147.  
  148. 2. **Important Project-Specific Details**:
  149. - Project Type: Plugin, theme, or template
  150. - Purpose: What problem does this solve?
  151. - Status: Production, beta, or template
  152. - Key Features: List main features
  153. - Architecture: File structure and organization patterns
  154.  
  155. 3. **Maintenance Tasks**:
  156. - List ongoing maintenance requirements
  157. - Note any dependencies that need regular updates
  158. - Mention any sync requirements for reference materials
  159.  
  160. 4. **Project-Specific Conventions**:
  161. - Code organization patterns
  162. - Naming conventions
  163. - Settings structure
  164. - Any project-specific patterns
  165.  
  166. 5. **Project-Specific References**:
  167. - Add entries for any reference projects (like UI Tweaker)
  168. - Format: `.ref/plugins/plugin-name/` - Brief description of why it's referenced
  169. - Note: The 6 core Obsidian projects are always relevant (don't list them here)
  170.  
  171. 6. **Overrides (Optional)**:
  172. - List any project-specific overrides to general `.agents` guidance
  173. - If none, state "None currently. This project follows the general `.agents` guidance."
  174.  
  175. 7. **Key Files and Their Purposes**:
  176. - List important files and what they do
  177. - Include the settings compatibility utility if created
  178. - Note any unusual file structures
  179.  
  180. 8. **Development Notes**:
  181. - Any important implementation details
  182. - Reference patterns used (e.g., SettingGroup implementation)
  183. - Notes about backward compatibility
  184. - Any gotchas or important considerations
  185.  
  186. ## Important Guidelines
  187.  
  188. 1. **SettingsGroup Pattern**:
  189. - First group: NO heading (use `createSettingsGroup(containerEl)`) - *unless* one already exists
  190. - Later groups (if they exist): WITH headings (use `createSettingsGroup(containerEl, 'Group Name')`)
  191. - Only create groups if settings naturally belong together
  192. - Don't force category names if they don't exist naturally
  193.  
  194. 2. **DOM Structure Rules**:
  195. - **NEVER** create divs directly on `containerEl` outside of SettingGroup structure
  196. - All content must go through `group.addSetting()` to maintain proper spacing
  197. - SettingGroup automatically handles spacing between groups - don't add manual spacers
  198. - If you need custom containers, add them as settings within groups (see "Custom Containers" above)
  199.  
  200. 3. **Version Checking**:
  201. - Always use `requireApiVersion('1.11.0')` to check for SettingGroup support
  202. - The compatibility utility handles fallback for older Obsidian versions
  203. - This allows the plugin to work on both old and new Obsidian versions
  204.  
  205. 4. **Code Quality**:
  206. - Maintain existing functionality - only change the grouping mechanism
  207. - Follow TypeScript best practices
  208. - Use proper error handling
  209. - Match the code style of the existing codebase
  210. - Remove legacy/empty containers that break spacing
  211.  
  212. 5. **Reference Implementation**:
  213. - **Study UI Tweaker carefully** - it demonstrates the correct pattern
  214. - UI Tweaker only uses `addSetting()` - it never creates divs directly on `containerEl`
  215. - Follow UI Tweaker's exact structure for spacing and grouping
  216.  
  217. 6. **Documentation**:
  218. - Be thorough in AGENTS.md - derive information from README.md and codebase analysis
  219. - Use clear, descriptive language
  220. - Follow the existing format and structure
  221.  
  222. ## Common Pitfalls to Avoid
  223.  
  224. 1. **Creating containers outside groups**: This breaks spacing. Always use `addSetting()`.
  225. 2. **Empty legacy containers**: Remove any empty containers created for "backward compatibility" - they break spacing even if empty.
  226. 3. **Moving settings out of groups**: Keep all settings within their group structure for proper spacing.
  227. 4. **Manual spacing**: Don't add spacer divs - SettingGroup handles spacing automatically.
  228. 5. **Using `\n` for line breaks**: Use `DocumentFragment` instead for multi-line descriptions.
  229. 6. **Conditional visibility containers**: Apply visibility classes to `setting.settingEl`, not separate containers.
  230.  
  231. ## Verification Steps
  232.  
  233. After completing all tasks:
  234.  
  235. 1. Verify the symlink to UI Tweaker works: `list_dir .ref/plugins/obsidian-ui-tweaker`
  236. 2. Verify the settings-compat.ts file was created correctly
  237. 3. Verify the settings tab imports and uses the compatibility utility
  238. 4. Verify AGENTS.md has all sections filled in with relevant information
  239. 5. Check that the code compiles: `npm run build` (or `npm run dev`)
  240. 6. Verify no linter errors: `npm run lint`
  241. 7. **Visual check**: Open settings and verify:
  242. - Proper spacing between groups
  243. - No broken/empty settings blocks
  244. - No crowded spacing between sections
  245. - Conditional visibility works correctly
  246.  
  247. ## Notes
  248.  
  249. - The UI Tweaker plugin serves as a reference implementation for SettingsGroup usage
  250. - The first group in UI Tweaker (auto-hide elements) has no heading - follow this pattern
  251. - Only create additional groups if settings naturally group together - don't force it
  252. - The compatibility utility ensures the plugin works on both Obsidian 1.11.0+ and older versions
  253. - **Key insight**: SettingGroup manages its own DOM structure and spacing - work within it, not around it
Advertisement
Comments
  • User was banned
  • User was banned
  • User was banned
  • User was banned
  • User was banned
  • User was banned
  • User was banned
  • User was banned
Add Comment
Please, Sign In to add comment