How akosbalasko/zoottelkeeper-obsidian-plugin works
1. Repository purpose and runtime boundary
- This is an Obsidian plugin written in TypeScript. Its runtime boundary is the Obsidian app and its vault filesystem.
- The plugin’s job is to keep “index” notes in sync with folder structure, so each folder can have an autogenerated note that links to its children.
2. Top-level orchestration lives in main.ts
- main.ts is the entry point and likely contains the plugin class lifecycle: load settings, register commands/settings UI, subscribe to vault file events, and trigger index regeneration.
- It is the central coordinator that connects vault events and manual actions to the lower-level helpers in utils/.
3. Configuration is a first-class subsystem
- defaultSettings.ts provides the baseline plugin configuration.
- interfaces/ZottelkeeperPluginSettings.ts and related interface files define the settings shape and typed options.
- The settings model includes behaviors that materially affect architecture: index prefix, list style, sorting order, folder include/exclude rules, frontmatter/meta tags, template path, and whether to embed sub-index content.
4. Folder scoping and filtering is separated from content generation
- utils/isInSpecificFolder.ts and utils/cleanDisallowedFolders.ts implement the boundary rules for which folders are managed.
- The readme indicates include/exclude paths are evaluated against absolute vault paths, with optional recursive matching using *.
- This filtering step determines which folders get index files and prevents updates in disallowed regions of the vault.
5. Index file identification and lifecycle
- The plugin appears to recognize index notes by a configurable prefix and/or by matching the folder name.
- consts.ts likely stores sentinel strings and constants used to detect autogenerated regions and preserve custom content.
- The lifecycle is: detect folder scope → locate/create corresponding index note → update only the autogenerated section.
6. Autogenerated content is updated surgically
- utils/updateIndexContent.ts is the core content generator/updater.
- The readme describes a protected region delimited by “beginning/end of autogenerated index file list” markers; the plugin updates only that region and leaves surrounding manual content intact.
- This is the main architectural boundary between autogenerated data and user-authored note content.
7. Frontmatter handling is isolated
- utils/hasFrontmatter.ts, getFrontmatter.ts, removeFrontmatter.ts, and updateFrontmatter.ts form a dedicated frontmatter subsystem.
- These helpers let the plugin detect YAML frontmatter, read existing metadata, preserve or strip it as needed, and rewrite tags/meta fields consistently.
- This is important because the plugin can optionally add YAML metadata to generated index notes.
8. File content model and sorting are explicitly modeled
- The models/ folder, especially models/sortOrder.ts, suggests sorting is treated as a domain concern rather than ad hoc string handling.
- interfaces/GeneralContentOptions.ts and interfaces/IndexItemStyle.ts likely define how list entries are rendered: plain links, bullet lists, or checkbox links.
- These options influence the shape of the generated index content but not the vault traversal logic.
9. External plugin/template integration is a deliberate extension point
- The readme shows integration with the Templater Obsidian plugin for pre-seeding index notes with placeholders.
- Zoottelkeeper respects template-managed notes by updating only the designated autogenerated block, which allows custom surrounding text while still regenerating folder listings.
- This is an integration boundary, not a hard dependency in the codebase itself.
10. Build and packaging
- rollup.config.js, tsconfig.json, manifest.json, styles.css, and versions.json show a standard Obsidian plugin packaging pipeline.
- Rollup bundles the TypeScript plugin for distribution; manifest.json describes plugin metadata for Obsidian; styles.css contains UI styling for the plugin settings or generated note presentation.
11. End-to-end data flow
- On startup or file/folder changes, the plugin scans the vault.
- It filters folders by include/exclude rules.
- For each eligible folder, it resolves the target index note, reads existing note content/frontmatter, generates a sorted list of children, and writes back only the managed section.
- The result is a set of stable folder-index notes that automatically track vault structure without overwriting custom content outside the autogenerated block.
12. Architectural shape
- The repo is organized as a small, single-purpose plugin with a clear split between:
- orchestration (main.ts)
- configuration and typed settings (interfaces/, defaultSettings.ts)
- domain helpers for vault path handling and frontmatter (utils/)
- rendering/sorting models (models/)
- There are no obvious backend services or multi-process boundaries; everything operates inside the Obsidian host against local vault files.
Main entry points: updateIndexContent.ts Index updater · main.ts Main plugin · ZottelkeeperPluginSettings.ts Plugin settings · GeneralContentOptions.ts Content options
Components 19
Runtime
Obsidian plugin execution inside the vault
- Main plugin · Plugin lifecycle, commands, event hooks, and sync orchestration
main.ts
Configuration
Typed settings and defaults
- Defaults · Baseline plugin configuration
defaultSettings.ts - Plugin settings · Typed settings shape and options
interfaces/ZottelkeeperPluginSettings.ts - Content options · Controls for generated list style and content shape
interfaces/GeneralContentOptions.ts - Item style · Styles for index entries and list presentation
interfaces/IndexItemStyle.ts - Interfaces barrel · Convenience exports for type definitions
interfaces/index.ts
Content Sync
Folder scanning, filtering, and index note updates
- Folder filter · Include/exclude and recursive path matching
utils/isInSpecificFolder.ts - Disallowed cleanup · Prunes folders outside the managed scope
utils/cleanDisallowedFolders.ts - Index updater · Surgically updates the autogenerated index block
utils/updateIndexContent.ts - Utils barrel · Convenience exports for utility helpers
utils/index.ts
Metadata
Frontmatter handling
- Has frontmatter · Detects whether a note has YAML frontmatter
utils/hasFrontmatter.ts - Read frontmatter · Extracts existing frontmatter data
utils/getFrontmatter.ts - Strip frontmatter · Removes frontmatter for controlled rewriting
utils/removeFrontmatter.ts - Write frontmatter · Rewrites tags and metadata for index notes
utils/updateFrontmatter.ts
Domain Models
Shared sort and content types
- Sort order · Sorting rules for generated folder listings
models/sortOrder.ts - Content models · Shared types for generated content and item rendering
models/index.ts
Packaging
Build and plugin distribution files
- Build config · Rollup bundling for the Obsidian plugin
rollup.config.js - Plugin manifest · Obsidian plugin metadata and activation info
manifest.json - Styles · Plugin and note presentation styling
styles.css
Connections 21
- Defaults → Plugin settings: populate · Defaults initialize the typed settings shape
- Plugin settings → Main plugin: configure · Main plugin consumes the settings model
- Content options → Main plugin: shape output · Rendering options influence index generation
- Item style → Content options: type option · Item style is one of the content rendering choices
- Main plugin → Folder filter: scope folders · Plugin checks whether a vault folder is managed
- Main plugin → Disallowed cleanup: prune scope · Managed folder sets are cleaned before updates
- Folder filter → Disallowed cleanup: feeds · Folder inclusion rules drive pruning decisions
- Main plugin → Index updater: update notes · Main orchestration triggers index regeneration
- Index updater → Sort order: sort children · Generated entries are ordered by the domain sort model
- Index updater → Has frontmatter: inspect · Updater checks whether metadata is present
- Index updater → Read frontmatter: read metadata · Existing YAML is read before rewriting
- Index updater → Strip frontmatter: preserve body · Frontmatter can be removed while updating managed content
- Index updater → Write frontmatter: rewrite metadata · Metadata is rewritten when plugin settings require it
- Read frontmatter → Write frontmatter: round-trip · Existing metadata informs the new frontmatter
- Content models → Index updater: data shapes · Generated content uses shared domain types
- Utils barrel → Folder filter: export · Utility barrel exposes helper functions
- Utils barrel → Index updater: export · Utility barrel exposes the content updater
- Interfaces barrel → Plugin settings: export · Interface barrel exposes settings types
- Interfaces barrel → Content options: export · Interface barrel exposes content option types
- Build config → Plugin manifest: package · Bundled output is described by plugin metadata
- Build config → Styles: include · Distribution package includes plugin styling