Community Themes

Inkdown supports a community theme system that allows you to share your themes and use themes created by others.

Installing Community Themes

From the UI

Open Settings → Appearance → Themes
Click Browse Community Themes
Browse available themes in the gallery
Click Install on any theme you like
The theme will be downloaded and appear in your theme list

Theme Installation Flow

When you install a community theme: Source: From theme-system.md documentation

Publishing Your Theme

Step 1: Create Your Theme

Follow the quickstart guide to create your theme locally. Your theme should have:

my-theme/
├── manifest.json    # Required: Theme metadata
├── dark.css        # Required for dark mode
├── light.css       # Required for light mode (if supported)
└── README.md       # Optional: Documentation

Step 2: Create GitHub Repository

Create a new repository on GitHub:

# Initialize repository
cd my-theme
git init

# Add files
git add manifest.json dark.css light.css README.md
git commit -m "Initial theme release"

# Create repository on GitHub and push
git remote add origin https://github.com/yourusername/my-theme.git
git branch -M main
git push -u origin main

Step 3: Create manifest.json

Ensure your manifest.json is complete and accurate:

{
  "name": "My Awesome Theme",
  "author": "Your Name",
  "version": "1.0.0",
  "description": "A beautiful theme with vibrant colors and great contrast",
  "homepage": "https://github.com/yourusername/my-awesome-theme",
  "modes": ["dark", "light"]
}

Step 4: Submit to Community Registry

The community theme registry is a curated list maintained by the Inkdown team.

Fork the inkdown-themes repository
Add your theme to themes.json:

{
  "themes": [
    {
      "id": "my-awesome-theme",
      "name": "My Awesome Theme",
      "author": "Your Name",
      "repo": "yourusername/my-awesome-theme",
      "branch": "main",
      "modes": ["dark", "light"]
    }
  ]
}

Create a pull request with:
- Theme entry in themes.json
- Screenshot showing your theme
- Brief description of your theme’s design philosophy

Step 5: Maintain Your Theme

As you update your theme:

Update the version in manifest.json
Document changes in your README.md
Create a new release on GitHub
Users will see an update notification in Inkdown

Theme Requirements

To be accepted into the community registry, themes must:

Technical Requirements

✅ Valid manifest.json with all required fields
✅ At least one CSS file (dark.css or light.css)
✅ CSS uses only documented theme variables
✅ No JavaScript or executable code
✅ Proper semantic versioning

Quality Requirements

✅ Readable text with sufficient contrast (WCAG AA minimum)
✅ All UI elements styled appropriately
✅ Tested with various markdown content
✅ No broken colors or invisible elements
✅ Includes preview screenshots

Repository Requirements

✅ Public GitHub repository
✅ README.md with theme description and screenshots
✅ License file (MIT, Apache, or similar permissive license)
✅ No malicious or tracking code

Theme Discovery

Caching Strategy

The CommunityThemeManager uses in-memory caching to improve performance:

interface CommunityThemeCache {
    lastFetched: number;                      // Timestamp for TTL check
    listings: CommunityThemeListing[];        // Basic theme info from registry
    themes: Record<string, CommunityTheme>;   // Full theme details (on-demand)
}

TTL: 1 hour
Invalidation: Manual refresh or automatic on TTL expiry
Storage: In-memory only (not persisted between sessions)

Source: From theme-system.md documentation

Features

Feature	Description
Browse Themes	Fetches theme listings from the community registry
Caching	In-memory cache with 1-hour TTL
Install/Uninstall	Downloads and saves theme files locally
Version Tracking	Tracks installed versions for update detection

Managing Installed Themes

View Installed Themes

All installed themes appear in Settings → Appearance → Themes:

Built-in themes (Default Dark, Default Light)
Custom themes (locally created)
Community themes (installed from GitHub)

Update Themes

When a theme author releases an update:

Inkdown checks for updates when browsing community themes
An “Update” button appears for outdated themes
Click to download and install the latest version
Your current theme settings are preserved

Uninstall Themes

To remove a community theme:

Open Settings → Appearance → Themes
Find the theme you want to remove
Click the trash icon or Uninstall button
Theme files are removed from disk
If the theme was active, Inkdown switches to the default theme

Theme Repository Structure

Recommended repository structure for sharing your theme:

my-awesome-theme/
├── manifest.json           # Theme metadata
├── dark.css               # Dark mode styles
├── light.css              # Light mode styles
├── README.md              # Documentation
├── LICENSE                # License file
├── screenshots/           # Preview images
│   ├── dark-preview.png
│   └── light-preview.png
└── examples/              # Example markdown files
    ├── demo.md
    └── syntax-test.md

README Template

Use this template for your theme’s README:

# My Awesome Theme

A beautiful Inkdown theme with vibrant colors and excellent readability.

## Preview

### Dark Mode
![Dark mode preview](screenshots/dark-preview.png)

### Light Mode
![Light mode preview](screenshots/light-preview.png)

## Features

- 🎨 Vibrant accent colors for better visual hierarchy
- 👁️ Carefully tuned contrast for extended reading
- ✨ Beautiful syntax highlighting for code blocks
- 🌙 Full dark and light mode support

## Installation

### From Inkdown (Recommended)

1. Open Settings → Appearance → Themes
2. Click "Browse Community Themes"
3. Search for "My Awesome Theme"
4. Click "Install"

### Manual Installation

1. Download this repository
2. Copy to your themes directory:
   - macOS: `~/Library/Application Support/com.furqas.inkdown/themes/`
   - Linux: `~/.config/inkdown/themes/`
   - Windows: `%APPDATA%/inkdown/themes/`
3. Restart Inkdown

## Design Philosophy

[Describe your design choices, color palette inspiration, and intended use cases]

## License

MIT License - feel free to modify and share!

Best Practices for Theme Authors

1. Provide Good Screenshots

Show your theme with real content:

Different heading levels
Bold, italic, links
Code blocks with syntax highlighting
Lists and blockquotes
Tables and callouts

2. Document Color Choices

Explain your color palette:

## Color Palette

- **Primary**: #0969da - Trustworthy blue for interactive elements
- **Success**: #2ea043 - Vibrant green for positive actions
- **Warning**: #fb8500 - Attention-grabbing orange
- **Danger**: #cf222e - Clear red for destructive actions

3. Support Both Modes

If possible, provide both light and dark modes. This makes your theme more versatile and accessible.

4. Version Your Releases

Use semantic versioning:

1.0.0 - Initial release
1.1.0 - Add light mode support
1.1.1 - Fix heading colors
2.0.0 - Major redesign

5. Respond to Issues

Monitor your theme repository for:

Bug reports (colors not working)
Feature requests (add light mode)
Accessibility concerns (contrast issues)

6. Test Thoroughly

Before publishing:

Test with all markdown elements
Check contrast ratios
Try different font sizes
Test on different displays
Get feedback from others

Theme Metadata Types

CommunityThemeListing

From the community registry index:

interface CommunityThemeListing {
    id: string;           // Unique identifier
    name: string;         // Display name
    author: string;       // Author name
    repo: string;         // GitHub repo (e.g., "author/repo")
    branch?: string;      // Branch name (default: "main")
    modes: ColorScheme[]; // Supported modes
}

Source: From theme-system.md documentation

FAQ

How long does theme review take?

Theme submissions are typically reviewed within 1-2 weeks. Complex themes or those requiring changes may take longer.

Can I update my theme after publishing?

Yes! Just update your GitHub repository and bump the version in manifest.json. Users will be notified of the update.

What if my theme is rejected?

You’ll receive feedback on what needs to be fixed. Most rejections are for contrast issues or incomplete themes.

Can I monetize my theme?

Community registry themes must be free and open source. You can accept donations or create paid themes distributed separately.

How do I remove my theme from the registry?

Submit a pull request removing your theme from themes.json. Your repository can remain public.

Next Steps

Quick Start

Create your first theme

Best Practices

Tips for creating great themes

CSS Variables

Complete variable reference

​Installing Community Themes

​From the UI

​Theme Installation Flow

​Publishing Your Theme

​Step 1: Create Your Theme

​Step 2: Create GitHub Repository

​Step 3: Create manifest.json

​Step 4: Submit to Community Registry

​Step 5: Maintain Your Theme

​Theme Requirements

​Technical Requirements

​Quality Requirements

​Repository Requirements

​Theme Discovery

​Caching Strategy

​Features

​Managing Installed Themes

​View Installed Themes

​Update Themes

​Uninstall Themes

​Theme Repository Structure

​README Template

​Best Practices for Theme Authors

​1. Provide Good Screenshots

​2. Document Color Choices

​3. Support Both Modes

​4. Version Your Releases

​5. Respond to Issues

​6. Test Thoroughly

​Theme Metadata Types

​CommunityThemeListing

​FAQ

​Next Steps

Quick Start

Best Practices

CSS Variables

Installing Community Themes

From the UI

Theme Installation Flow

Publishing Your Theme

Step 1: Create Your Theme

Step 2: Create GitHub Repository

Step 3: Create manifest.json

Step 4: Submit to Community Registry

Step 5: Maintain Your Theme

Theme Requirements

Technical Requirements

Quality Requirements

Repository Requirements

Theme Discovery

Caching Strategy

Features

Managing Installed Themes

View Installed Themes

Update Themes

Uninstall Themes

Theme Repository Structure

README Template

Best Practices for Theme Authors

1. Provide Good Screenshots

2. Document Color Choices

3. Support Both Modes

4. Version Your Releases

5. Respond to Issues

6. Test Thoroughly

Theme Metadata Types

CommunityThemeListing

FAQ

Next Steps