TEMPLATE_USAGE.md

Template Usage Guide

This guide explains how to use this template to create your own Obsidian plugin.

Prerequisites

• Bun installed (latest version)
• Git installed
• A GitHub account
• An Obsidian vault for testing

Step 1: Create Your Repository

Option A: Use GitHub Template (Recommended)

1. Click the "Use this template" button on the GitHub repository page
2. Choose a name for your repository (e.g., obsidian-my-awesome-plugin)
3. Clone your new repository:

git clone https://github.com/YOUR_USERNAME/obsidian-my-awesome-plugin.git
cd obsidian-my-awesome-plugin

Option B: Manual Clone

1. Clone this repository:

git clone https://github.com/dsebastien/obsidian-plugin-template-bun.git obsidian-my-awesome-plugin
cd obsidian-my-awesome-plugin

2. Remove the existing git history and initialize a new repository:

rm -rf .git
git init
git add .
git commit -m "Initial commit from template"

3. Create a new repository on GitHub and push:

git remote add origin https://github.com/YOUR_USERNAME/obsidian-my-awesome-plugin.git
git branch -M main
git push -u origin main

Step 2: Update Project Metadata

2.1 Update package.json

Update the following fields with your project information:

{
    "name": "obsidian-my-awesome-plugin",
    "description": "Your plugin description here",
    "author": {
        "name": "Your Name",
        "email": "your-email@example.com",
        "url": "https://your-website.com"
    },
    "keywords": ["obsidian", "obsidian-plugin", "your-keywords"],
    "repository": {
        "type": "git",
        "url": "git+https://github.com/YOUR_USERNAME/obsidian-my-awesome-plugin.git"
    },
    "bugs": {
        "url": "https://github.com/YOUR_USERNAME/obsidian-my-awesome-plugin/issues"
    },
    "homepage": "https://github.com/YOUR_USERNAME/obsidian-my-awesome-plugin"
}

2.2 Update manifest.json

Update the plugin manifest with your plugin details:

{
    "id": "my-awesome-plugin",
    "name": "My Awesome Plugin",
    "description": "Your plugin description here",
    "version": "1.0.0",
    "minAppVersion": "1.4.0",
    "isDesktopOnly": false,
    "author": "Your Name",
    "authorUrl": "https://your-website.com",
    "fundingUrl": "https://www.buymeacoffee.com/your-username"
}

Important notes about manifest.json:

• The id field must be unique and should match your plugin folder name
• Never change id after releasing your plugin
• Use semantic versioning (e.g., 1.0.0, 1.1.0, 2.0.0)
• Update minAppVersion if you use newer Obsidian APIs

Step 3: Rename Plugin Classes

Search for TODO comments in the source code and update the following:

3.1 Plugin Class (src/app/plugin.ts)

Rename MyPlugin to your plugin class name:

// Before
export class MyPlugin extends Plugin {

// After
export class MyAwesomePlugin extends Plugin {

3.2 Settings Tab Class (src/app/settings/settings-tab.ts)

Rename MyPluginSettingTab to match your plugin name:

// Before
export class MyPluginSettingTab extends PluginSettingTab {

// After
export class MyAwesomePluginSettingTab extends PluginSettingTab {

Also update the type imports:

// Before
import type MyPlugin from '../../main'

// After
import type MyAwesomePlugin from '../../main'

3.3 Main Entry Point (src/main.ts)

Update the import and export:

// Before
import { MyPlugin } from './app/plugin'
export default MyPlugin

// After
import { MyAwesomePlugin } from './app/plugin'
export default MyAwesomePlugin

3.4 Settings Tab Social Links (Optional)

The settings tab in src/app/settings/settings-tab.ts includes social media and support links for the template author. You can:

• Keep them: If you want to support the template author
• Update them: Replace with your own Twitter/X handle, Buy Me a Coffee URL, etc.
• Remove them: Delete the renderFollowButton, renderSupportHeader, and renderBuyMeACoffeeBadge methods and their calls in display()

3.5 GitHub Funding (Optional)

The .github/FUNDING.yml file contains funding links for the template author. You can:

• Keep it: If you want to support the template author
• Update it: Replace with your own funding information
• Remove it: Delete the file entirely if you don't want funding links

Step 4: Update Documentation

4.1 Update README.md

Replace the template README with your plugin's documentation:

• Plugin name and description
• Features list
• Installation instructions
• Usage guide
• Configuration options
• Screenshots (if applicable)

4.2 Update CONTRIBUTING.md

Update repository URLs and any project-specific contribution guidelines.

4.3 Update DEVELOPMENT.md

Update repository URLs and the plugin folder name in the manual installation section.

4.4 Update or Remove .github/FUNDING.yml

See Step 3.5 above for guidance on the funding file.

Step 5: Configure GitHub

5.1 Repository Settings

1. Go to your repository Settings → Actions → General
2. Under "Workflow permissions", enable Read and write permissions
3. Check "Allow GitHub Actions to create and approve pull requests"

5.2 Enable GitHub Pages (Optional)

If you want to host documentation:

1. Go to Settings → Pages
2. Set source to "GitHub Actions" or your preferred branch

Step 6: Install Dependencies

bun install

Step 7: Configure Development Environment

Set the OBSIDIAN_VAULT_LOCATION environment variable to your test vault path:

Linux/macOS

export OBSIDIAN_VAULT_LOCATION="/path/to/your/vault"

Add to ~/.bashrc or ~/.zshrc to make it permanent.

Windows (PowerShell)

$env:OBSIDIAN_VAULT_LOCATION="C:\Users\YourName\Documents\ObsidianVault"

Step 8: Start Development

1. Start TypeScript watch mode (recommended to run in a separate terminal):

bun run tsc:watch

2. Start the development build:

bun run dev

3. In Obsidian:
   • Go to Settings → Community plugins
   • Enable the plugin
   • Use Ctrl/Cmd + R to reload after changes

Step 9: Clean Up Template Files

After completing the setup, remove this file:

rm TEMPLATE_USAGE.md

Also review and clean up:

• documentation/ folder - update or remove template documentation
• TODO.md - if present, review and update for your project

Creating Your First Release

For the first release, do not use automated version bumping. Instead:

1. Ensure your code is ready and all tests pass:

bun run tsc
bun run lint
bun test
bun run build

2. Create and push a tag:

git tag 1.0.0
git push origin 1.0.0

3. The GitHub Actions release workflow will automatically:
   • Build the plugin
   • Generate a changelog
   • Create a GitHub release with the necessary files

Subsequent Releases

For subsequent releases, you can either:

Manual Tag (Recommended for major releases)

git tag 1.1.0
git push origin 1.1.0

Workflow Dispatch

1. Go to Actions → Release in your repository
2. Click "Run workflow"
3. Enter the version number (e.g., 1.1.0)
4. Click "Run workflow"

Publishing to Obsidian Community Plugins

When you're ready to publish:

1. Ensure your plugin follows Obsidian's plugin guidelines
2. Review the submission requirements
3. Submit a PR to obsidian-releases

Template Features Overview

This template includes:

Feature	Description
Bun	Fast package manager and bundler
TypeScript	Strict type checking enabled
Tailwind CSS v4	Utility-first CSS framework
ESLint	Code linting with modern config
Prettier	Code formatting
Husky	Git hooks for pre-commit checks
lint-staged	Run linters on staged files
Commitizen	Interactive commit message helper
Conventional Commits	Standardized commit message format
GitHub Actions CI	Automated testing on push/PR
GitHub Actions Release	Automated release workflow
Immer	Immutable state management
Zod	Runtime type validation

Troubleshooting

Bun not found

Install Bun from bun.sh:

curl -fsSL https://bun.sh/install | bash

Plugin not appearing in Obsidian

1. Verify OBSIDIAN_VAULT_LOCATION is correct
2. Check files exist in <vault>/.obsidian/plugins/<plugin-id>/
3. Restart Obsidian
4. Ensure Community plugins are enabled

TypeScript errors

Run bun run tsc:watch to see detailed type errors and fix them before building.

Build fails

1. Ensure all dependencies are installed: bun install
2. Check for TypeScript errors: bun run tsc
3. Check for lint errors: bun run lint

Questions?

If you encounter issues with this template, please open an issue on the template repository.