Themes

Inkdown provides a flexible theming system that allows you to customize the editor’s appearance to match your preferences and reduce eye strain.

Built-in Themes

Inkdown includes two built-in themes:

Default Dark

ID: default-dark
Name: Default Dark
Author: Inkdown
Color Scheme: Dark mode
Description: A carefully crafted dark theme with excellent contrast and readability

Default Light

ID: default-light
Name: Default Light
Author: Inkdown
Color Scheme: Light mode
Description: A clean, minimal light theme for daytime use

Both themes are optimized for markdown editing with clear syntax highlighting and comfortable contrast ratios.

Color Schemes

Inkdown themes support two color schemes:

Dark: Low-luminance background, high-luminance text
Light: High-luminance background, low-luminance text

Each theme declares which color schemes it supports. Some custom themes may support both light and dark modes.

Switching Themes

Using Settings

Open Settings with Cmd/Ctrl+,
Navigate to Appearance
Select a theme from the Theme dropdown
The theme will be applied immediately

Programmatic Theme Switching

Themes can be changed programmatically through the ThemeManager:

// Switch to a specific theme
await app.themeManager.setTheme('default-dark');

// Get current theme
const currentTheme = app.themeManager.getCurrentTheme();
// Returns: 'default-dark' or 'default-light'

// Get current color scheme
const colorScheme = app.themeManager.getColorScheme();
// Returns: 'dark' or 'light'

Switching Color Scheme

You can switch between light and dark modes:

// Switch to dark mode
await app.themeManager.setColorScheme('dark');

// Switch to light mode
await app.themeManager.setColorScheme('light');

If the current theme doesn’t support the selected color scheme, Inkdown automatically switches to the default theme for that scheme.

How Themes Work

CSS Variables

Inkdown uses CSS variables for theming, allowing instant theme changes without page reload:

:root {
  --color-bg: #1a1a1a;
  --color-text: #e0e0e0;
  --color-primary: #6b9eff;
  --color-border: #333333;
  /* ... more variables */
}

Theme Architecture

The theming system consists of several components:

ThemeManager: Core state management and event emission
ThemeConfig: Theme metadata (name, author, supported modes)
ParsedTheme: Theme colors as JavaScript objects
CSS Content: Actual CSS variables for custom themes

Platform-Specific Rendering

Desktop: DOMThemeRenderer applies CSS to the document
Mobile: ExpoThemeContext provides theme via React Context

Themes work consistently across both platforms.

Installing Community Themes

Custom theme installation is coming in a future update. The theme system architecture is in place, and community theme support will be enabled soon.

Theme Directory Structure

Custom themes are stored in the themes directory with this structure:

themes/
└── theme-name/
    ├── manifest.json    # Theme metadata
    ├── dark.css        # Dark mode styles
    └── light.css       # Light mode styles (optional)

Theme Manifest

Each theme includes a manifest.json file:

{
  "name": "My Custom Theme",
  "author": "Your Name",
  "version": "1.0.0",
  "description": "A beautiful custom theme",
  "homepage": "https://github.com/username/inkdown-theme",
  "modes": ["dark", "light"]
}

Theme CSS Files

Theme CSS files define color variables:

/* dark.css */
:root {
  /* Background colors */
  --color-bg: #1e1e1e;
  --color-bg-secondary: #252525;
  --color-bg-tertiary: #2d2d2d;
  
  /* Text colors */
  --color-text: #d4d4d4;
  --color-text-secondary: #a0a0a0;
  --color-text-muted: #707070;
  
  /* Accent colors */
  --color-primary: #4a9eff;
  --color-success: #4ec9b0;
  --color-warning: #ce9178;
  --color-error: #f48771;
  
  /* Editor syntax */
  --color-syntax-keyword: #569cd6;
  --color-syntax-string: #ce9178;
  --color-syntax-comment: #6a9955;
  --color-syntax-function: #dcdcaa;
  
  /* UI elements */
  --color-border: #3e3e3e;
  --color-hover: #2a2a2a;
  --color-active: #0e639c;
}

Installing a Theme (Coming Soon)

Once community theme support is enabled:

Download the theme folder
Open Settings > Appearance
Click Install Theme
Select the theme folder
The theme will appear in your theme list

Reloading Themes

After installing or modifying themes:

await app.themeManager.reloadCustomThemes();

This refreshes the theme list without restarting the application.

Creating Custom Themes

Theme Development

To create a custom theme:

Create a new directory in the themes folder
Add a manifest.json with theme metadata
Create dark.css and/or light.css files
Define CSS variables for all required colors
Test the theme in Inkdown

Required CSS Variables

Your theme should define these essential variables: Background

--color-bg: Main background
--color-bg-secondary: Secondary backgrounds
--color-bg-tertiary: Tertiary backgrounds

Text

--color-text: Primary text
--color-text-secondary: Secondary text
--color-text-muted: Muted/disabled text

Accent Colors

--color-primary: Primary accent
--color-success: Success states
--color-warning: Warning states
--color-error: Error states

Editor

--color-syntax-*: Syntax highlighting colors
--color-border: Borders and dividers
--color-hover: Hover states
--color-active: Active/selected states

Theme Testing

Test your theme thoroughly:

Switch between color schemes
Check all UI elements (editor, sidebar, modals)
Verify syntax highlighting for various languages
Test in both editor and preview modes
Check contrast ratios for accessibility

Theme Events

Listen for theme changes in your plugins:

app.themeManager.on('theme-changed', (event: ThemeChangeEvent) => {
  console.log('Theme changed:', event.themeId);
  console.log('Color scheme:', event.colorScheme);
  console.log('Theme object:', event.theme);
  
  // CSS content is available for custom themes
  if (event.cssContent) {
    console.log('Custom theme CSS:', event.cssContent);
  }
});

Theme Change Event

The theme-changed event includes:

interface ThemeChangeEvent {
  themeId: string;           // e.g., 'default-dark'
  colorScheme: ColorScheme;  // 'dark' or 'light'
  theme: ParsedTheme;        // Parsed CSS variables
  cssContent?: string;       // Raw CSS for custom themes
}

Theme Persistence

Your theme preference is automatically saved and persisted across sessions:

Theme selection saved to app config
Color scheme preference remembered
Settings sync with workspace (if sync enabled)

Performance

Instant Switching

Theme changes are instant because:

CSS variables update without page reload
No JavaScript re-renders required
Theme state cached for quick access

Caching

The ThemeManager caches parsed theme objects:

const theme = await app.themeManager.getCurrentThemeObject();
// Subsequent calls return cached version

Accessibility

When creating themes, consider:

Contrast Ratios: Minimum 4.5:1 for normal text, 3:1 for large text
Color Blindness: Don’t rely solely on color to convey information
Focus Indicators: Ensure focus states are clearly visible
Reduced Motion: Avoid theme-related animations

Troubleshooting

Theme Not Applying

Check console for errors
Verify theme files are in correct location
Ensure manifest.json is valid JSON
Reload custom themes

Missing Colors

If UI elements appear unstyled:

Check that all required CSS variables are defined
Verify variable names match exactly (case-sensitive)
Test with a built-in theme first

Performance Issues

If theme switching is slow:

Clear theme cache
Reduce number of custom themes
Check for CSS syntax errors

Next Steps

Optimize your editing workflow with Keyboard Shortcuts
Master the editor features in Editor Basics
Set up Sync to share themes across devices

Getting Started

Core Concepts

User Guide

Architecture

Documentation Index

​Themes

​Built-in Themes

​Default Dark

​Default Light

​Color Schemes

​Switching Themes

​Using Settings

​Programmatic Theme Switching

​Switching Color Scheme

​How Themes Work

​CSS Variables

​Theme Architecture

​Platform-Specific Rendering

​Installing Community Themes

​Theme Directory Structure

​Theme Manifest

​Theme CSS Files

​Installing a Theme (Coming Soon)

​Reloading Themes

​Creating Custom Themes

​Theme Development

​Required CSS Variables

​Theme Testing

​Theme Events

​Theme Change Event

​Theme Persistence

​Performance

​Instant Switching

​Caching

​Accessibility

​Troubleshooting

​Theme Not Applying

​Missing Colors

​Performance Issues

​Next Steps

Build docs developers (and LLMs) love

Themes

Built-in Themes

Default Dark

Default Light

Color Schemes

Switching Themes

Using Settings

Programmatic Theme Switching

Switching Color Scheme

How Themes Work

CSS Variables

Theme Architecture

Platform-Specific Rendering

Installing Community Themes

Theme Directory Structure

Theme Manifest

Theme CSS Files

Installing a Theme (Coming Soon)

Reloading Themes

Creating Custom Themes

Theme Development

Required CSS Variables

Theme Testing

Theme Events

Theme Change Event

Theme Persistence

Performance

Instant Switching

Caching

Accessibility

Troubleshooting

Theme Not Applying

Missing Colors

Performance Issues

Next Steps