Obsidian Courses

Manage color-coded CSS snippets for course notes in Obsidian. Assign primary and secondary colors to each course, and the plugin generates a CSS snippet that styles headers, highlights, inline titles, note backgrounds, and internal links to match.

Features

• Course management — Add, remove, and reorder courses through the settings tab
• Color pickers — Choose primary and secondary colors for each course
• Component toggles — Independently enable/disable Note Background, Inline Title, Headers (h1-h6), Highlight/Mark, and Internal Links
• Live preview — See the generated CSS in real time as you edit courses
• Import from snippet — Parse existing @course-annotated CSS snippets into your course list
• Auto-enable — Generated snippets are automatically saved to .obsidian/snippets/ and enabled
• CSS variable system — Each course exposes --course-primary and --course-secondary for use in other snippets

Usage

1. Install the plugin by copying main.js, manifest.json, and styles.css into .obsidian/plugins/obsidian-courses/
2. Go to Settings -> Courses
3. Add a course with a class name (e.g. math101) and choose primary/secondary colors
4. Click Generate & Save CSS Snippet
5. Add cssclasses: math101 to any note's frontmatter to apply the colors

Frontmatter Example

---
title: Calculus I
cssclasses:
  - math101
---

Settings

Setting	Description
Snippet filename	Customize the output CSS file name (default: obsidian-courses.css)
Note Background	Tint the note background with the course primary color
Inline Title	Color the inline title with the course secondary color
Headers	Color h1-h6 (h1 gets a background fill, h2-h6 get text colors)
Highlight / Mark	Style highlighted text with the course primary color
Internal Links	Color internal wiki links via --link-color CSS variable
Add Course	Add a new course row with auto-assigned default colors
Import from Snippet	Pull course data from an existing @course-annotated CSS file
Generate & Save CSS Snippet	Write the compiled CSS and enable the snippet
Copy CSS to Clipboard	Copy the generated CSS without saving

Development

Prerequisites

• Node.js 22+
• npm

Setup

git clone <repo-url>
cd obsidian-courses
npm install
cp .env.example .env

Edit .env and set OBSIDIAN_VAULT_PATH to the absolute path of your Obsidian vault.

Workflow

npm run dev          # Watch source files, auto-build and sync to vault
npm run build        # Type-check with tsc and bundle with vite
npm run sync         # Copy main.js, manifest.json, styles.css to vault
npm run lint         # Run tsc type-checking only

Commits

This project uses Conventional Commits enforced by commitlint and husky.

feat: add internal link coloring
fix: snippet path resolution on Windows
chore(deps): update obsidian types

Release

npm run release           # Patch bump (0.0.1 -> 0.0.2)
npm run release:minor     # Minor bump (0.0.1 -> 0.1.0)
npm run release:major     # Major bump (0.0.1 -> 1.0.0)

Each release command:

1. Runs npm run build to verify the plugin compiles
2. Bumps the version in package.json
3. Runs scripts/update-manifest.js to sync manifest.json
4. Stages both files and creates a version commit
5. Pushing the tag triggers the GitHub Release workflow

Project Structure

obsidian-courses/
├── src/
│   ├── main.ts          # Plugin entry point, settings handling
│   ├── models.ts         # Course and ComponentSettings types
│   ├── generator.ts      # CSS generation logic
│   ├── parser.ts         # CSS snippet parser for import
│   ├── settings.ts       # Settings tab UI
│   └── storage.ts        # Snippet file writing
├── scripts/
│   ├── sync-to-obsidian.sh   # Deploy built files to vault
│   └── update-manifest.js    # Sync manifest.json version on release
├── .github/workflows/
│   ├── ci.yml            # Runs build on PRs and pushes to main
│   └── release.yml       # Creates GitHub release on tags
├── styles.css            # Plugin settings UI styles
├── manifest.json         # Obsidian plugin manifest
├── cliff.toml            # git-cliff changelog configuration
├── commitlint.config.js  # Conventional commit validation
└── package.json          # Dependencies and scripts

CSS Output

The plugin generates a CSS snippet with @course / @endcourse markers for each course, enabling re-import later. Each course block defines CSS custom properties and scoped selectors:

/* @course math101 */

.math101 {
  --course-primary: #ffb86c;
  --course-secondary: #e6c560;
  --inline-title-color: #e6c560;
  --link-color: #ffb86c;
}

.markdown-source-view.mod-cm6.math101 .cm-header-1 {
  background-color: #ffb86ca6 !important;
}
/* ... more selectors ... */

/* @endcourse */

License

MIT