Contributing

Development setup

1. Clone the repository:

   git clone https://github.com/cybersader/postpartum-tracker.git
   cd postpartum-tracker

2. Install dependencies:

   bun install

3. Build the plugin:

   bun run build

4. For development with auto-rebuild:

   bun run dev

Project structure

The plugin source lives in src/. Build output (main.js) is generated in the project root alongside manifest.json and styles.css.

src/
  main.ts                           Plugin entry point
  types.ts                          All interfaces and defaults
  settings.ts                       Settings tab
  StatusBarManager.ts               Status bar display
  data/
    CodeBlockStore.ts               JSON persistence
    TrackerRegistry.ts              Module registration
    dateUtils.ts                    Day boundary helpers
  nlp/
    QuickEntryParser.ts             Rules-based NLP parser
  trackers/
    BaseTracker.ts                  TrackerModule interface
    library.ts                      SimpleTrackerDef catalog
    logicPacks.ts                   Logic pack milestone definitions
    milestoneEvaluator.ts           Milestone rule engine
    feeding/FeedingTracker.ts       Core: feeding
    feeding/feedingStats.ts
    diaper/DiaperTracker.ts         Core: diapers
    diaper/diaperStats.ts
    medication/MedicationTracker.ts Core: medication
    medication/medicationStats.ts
    comment/CommentTracker.ts       Core: notes & comments
    simple/SimpleTrackerModule.ts   Library: generic module class
    simple/simpleTrackerStats.ts
  widget/
    TrackerWidget.ts                Main widget (MarkdownRenderChild)
    CollapsibleSection.ts           Reorderable sections
    QuickActions.ts                 Button grid
    QuickEntrySection.ts            NLP quick entry UI
    DailySummary.ts                 Summary strip
    AlertsPanel.ts                  Health alerts
    EventHistorySection.ts          Unified event feed
    shared/
      BigButton.ts                  Touch-friendly buttons
      TimerDisplay.ts               Live timer component
      EntryList.ts                  Scrollable entry list
      InlineEditPanel.ts            Inline edit forms
      FieldRenderer.ts              Dynamic field rendering
  ui/
    TrackerEditModal.ts             Modal edit dialog
  integrations/
    TodoistService.ts               Todoist API v1
  notifications/
    NotificationService.ts          Periodic scanner + dispatch
    ToastNotification.ts            In-app toast UI
  utils/
    dom.ts                          DOM helpers
    formatters.ts                   Time/date formatting
    deepMerge.ts                    Settings merge utility

See Architecture for a detailed breakdown.

Build commands

Command	Description
bun run build	TypeScript type-check + esbuild bundle
bun run dev	Watch mode (rebuilds on file changes)
bun test	Run tests
npm run lint	ESLint with Obsidian plugin rules

Testing

The plugin directory is itself an Obsidian vault plugin folder. To test:

1. Build with bun run build.
2. Open the parent vault in Obsidian (the one containing .obsidian/plugins/obsidian-postpartum-tracker/).
3. Enable the plugin in Settings > Community Plugins.
4. Open Baby Tracker.md (or insert a new tracker code block).

The Hot Reload community plugin is recommended for automatic reloading during development.

Adding a new library tracker

The easiest way to contribute a new tracker is through the simple tracker system:

1. Add a SimpleTrackerDef to src/trackers/library.ts.
2. That’s it — rebuild and the tracker appears in the library.

See Simple tracker API for the full field reference.

Releasing

Releases are created via a shell script that bumps the version, creates a git tag, and pushes. GitHub Actions builds and publishes the release.

bash scripts/release.sh 0.4.0

This script:

1. Validates the version argument.
2. Updates manifest.json and versions.json via version-bump.mjs.
3. Runs bun run build.
4. Commits, tags, and pushes.
5. GitHub Actions creates a release with main.js, manifest.json, and styles.css.

Documentation site

The docs site (what you’re reading now) uses Astro Starlight and lives in the docs/ directory.

cd docs
bun install
bun run dev        # Local preview at localhost:4321
bun run build      # Production build

Documentation is deployed automatically to GitHub Pages when changes to docs/ are pushed to the main branch.

Code style

• Vanilla TypeScript + DOM (no framework)
• CSS class prefix: pt-
• Use pointerdown/pointerup for interactive elements in code blocks
• Sort entries by timestamp after mutations
• Keep modules self-contained — each module manages its own UI and state

Pull requests

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Run bun run build to verify the build succeeds.
5. Run npm run lint to check code quality.
6. Submit a pull request with a clear description of what changed and why.