Repository navigation
Settings & Customization
Flatnotes-Enhanced gives you complete control over the look and feel of your note-taking experience. The Settings page is organized into nine tabs: Callouts, Appearance, Advanced, Tags, Task Icons, Searches, Preferences, Branding, and Maintenance.
- Click Settings in the main navigation menu (hamburger/gear icon)
- Or navigate directly to the Settings page
- Choose a tab at the top to customize that aspect
- Changes are saved with the Save button for each section
Callouts are highlighted blocks that draw attention to important information. They use Obsidian-style syntax and can be fully customized.
Callouts are special formatted boxes with custom icons and colors:
> [!note]
>
> This is a note-type callout with an icon and custom color.
> Important: There always needs to be an empty line (with >) between the callout header (e.g., [!note]) and the body.
> [!warning]
>
> This is a warning — appears in the custom warning color.
> Important: There always needs to be an empty line (with >) between the callout header (e.g., [!note]) and the body.
> [!custom-type] Title
>
> Custom callout with your defined styling.
> Important: There always needs to be an empty line (with >) between the callout header (e.g., [!note]) and the body.Flatnotes-Enhanced comes with these pre-configured types:
| Type | Default Color | Icon | Description |
|---|---|---|---|
note |
Blue | Info circle | General information |
warning |
Orange | Warning triangle | Important warning |
danger |
Red | Exclamation | Critical alert |
info |
Cyan | Information | Additional details |
success |
Green | Checkmark | Success or completed |
Built-in types can be recolored but cannot be deleted.
-
Go to Settings → Callouts tab
-
Click "Add callout" button
-
Enter the following details:
-
Type: Unique identifier (lowercase, no spaces, e.g.,
tip,pro,gotcha) - Label: Display name (e.g., "Pro Tip", "Gotcha!")
-
Color: Click the color square or enter a hex code (e.g.,
#6F42C1) - Icon: Click the "Icon" button to choose from 100+ Material Design icons
-
Type: Unique identifier (lowercase, no spaces, e.g.,
-
See the live preview chip update as you customize
-
Click "Save callouts" when done
- Modify the fields for any callout
- The preview updates live
- Custom callouts can be deleted (click the trash icon)
- Built-in callouts show a lock icon—they can't be deleted
- Click "Save callouts" to apply changes
Once saved, use your custom callouts with the syntax:
> [!type]
> (always add an empty row)
> Your content here
> [!type] Optional Title
>
> Your content hereExample:
> [!pro]
>
> Use keyboard shortcuts to work faster!
> [!gotcha] Watch Out!
>
> This feature doesn't work with mobile devices.-
Use descriptive types:
how-to,quick-win,heads-upare clearer thanx,y,z - Color for meaning: Red for critical, green for success, blue for information
- Limited callouts: 5-10 is plenty; too many dilutes the impact
- Consistent naming: Stick to a naming convention (e.g., all lowercase, hyphens not underscores)
Customize how headings and text highlights appear in your notes.
Make your headings more visually distinct with custom colors.
- Go to Settings → Appearance tab
- Toggle "Enable custom header colors" ON
- A list of H1 through H6 heading levels appears
- Each heading can be colored individually or disabled
For each heading level (H1, H2, H3, H4, H5, H6):
- Color picker: Click the square to choose a color visually
-
Hex input: Or enter a hex color code directly (e.g.,
#0066FF) - Live preview: See how the heading looks with the chosen color
- Per-heading toggle: Enable/disable that specific heading's color
Workflow:
H1 Heading → #0066FF (Blue) → ✓ Enabled
H2 Heading → #28A745 (Green) → ✓ Enabled
H3 Heading → #FFC107 (Yellow) → ✓ Enabled
H4 Heading → #DC3545 (Red) → ✗ Disabled
H5 Heading → #6F42C1 (Purple) → ✓ Enabled
H6 Heading → #20C997 (Teal) → ✓ Enabled
- Use a consistent hierarchy: Darker colors for high-level headings (H1, H2)
- High contrast: Ensure colors work in both light and dark themes
- ** 3-6 colors max**: Too many colors looks cluttered
- Test in both modes: Colors may look different in light/dark theme
Example palette:
H1: #1e40af (Dark blue)
H2: #2563eb (Medium blue)
H3: #0891b2 (Teal)
H4: #059669 (Green)
H5: #d97706 (Orange)
H6: #9333ea (Purple)
Customize colors used when highlighting text in your notes.
- Toggle "Enable custom highlights" (if needed—usually always on)
- Click "Add color" to add a new highlight color
- For each color, set:
- Color picker: Choose the color visually
- Name: Label for the color (e.g., "Important", "Review", "Question")
- Hex code: Edit directly if needed
- Enabled toggle: Turn highlight on/off without deleting
- Default button: Mark one color as the default (used when clicking the toolbar highlight button)
- Only one color can be default
- The default is used when you click the highlight button in the editor toolbar
- Clicking "Default" on a color makes it the new default
- Built-in colors can't be deleted but can be recolored
Yellow #FFFF00 → General emphasis
Green #90EE90 → Completion/approved
Blue #87CEEB → Questions/review needed
Red #FFB6C6 → Critical/urgent
Orange #FFD700 → Important notice
Purple #DDA0DD → Custom/special note
Fine-tune how tables and blockquotes render in your notes.
Make tables in your notes more readable with custom header colors and row striping.
- Go to Settings → Advanced tab
- Toggle "Enable custom table styling" ON
- Two options appear: header color and zebra striping
Header Color:
- Click the color picker to choose the header background color
- Enter a hex code directly for exact color control
- Preview shows the header with your chosen color and white text
Zebra Striping:
- Toggle ON to alternate row background colors
- Improves readability of large tables
- OFF means all rows have the same background
| Project | Status | Owner |
|---------|--------|-------|
| Website | In progress | Alice |
| API | Complete | Bob |
| Mobile | Planned | Charlie |With styling enabled:
- Header: Custom color (e.g., dark blue) with white text
- Row 1: Light background (zebra)
- Row 2: Normal background
- Row 3: Light background (zebra)
- Header color: Use your brand color or a strong, dark color
- Contrast: Ensure white or light text shows clearly on header color
- Zebra striping: Very helpful for tables with many rows (10+)
- Not too bold: Zebra colors should be subtle (light gray, not bright colors)
Customize how blockquotes appear in your notes. Separate styling for light and dark themes.
- Go to Settings → Advanced tab
- Scroll to "Quote Styling" section
- Toggle "Enable custom quote styling" ON
- Three color options appear:
- Border color: Left border of the quote
- Light background: Background in light theme mode
- Dark background: Background in dark theme mode (with opacity control)
Border Color:
- The left border of blockquotes (visual accent)
- Typically a bold color to make quotes stand out
Light Mode Background:
- Background color when viewing in light theme
- Usually a light tint (pale blue, cream, etc.)
- White text typically shows clearly
Dark Mode Background:
- Background color when viewing in dark theme
- Use opacity control to make it subtle or prominent
- Opacity: 0% = fully transparent, 100% = fully opaque
- Helpful tip: Lower opacity (10-30%) often looks better in dark mode
> This is an important quote that deserves
> visual emphasis and a custom appearance.With custom styling:
- Left border:
#0084FF(blue) - Light background:
#E7F0FF(pale blue) - Dark background:
#1e40afat 20% opacity (subtle blue overlay)
- Border + background match: Use complementary colors (same hue)
- Readability: Ensure text is readable on the background
- Subtle in dark mode: Lower opacity preserves the dark theme feel
- Test both themes: Preview shows the current theme; test both if applicable
Customize tag colors for the entire application.
- Go to Settings → Tags tab
- Toggle "Enable custom tag colors" ON/OFF
- ON: Use your custom colors + system defaults
- OFF: All tags use the default auto-generated colors (settings are preserved)
- Used as fallback when custom colors aren't set
- Click the color picker to choose
- Shown as a preview chip on the right
- This color appears for any unassigned tag
When custom colors are enabled, you can assign specific colors to individual tags.
Method 1: Add Row Button
- Click "Add row" button
- Enter tag name (support for nested:
projects/infrastructure) - Choose color from picker
- Toggle enabled/disabled
- See live preview chip
Method 2: Click a Tag from List
- Scroll to "Your tags" section at the bottom
- Shows all tags currently in your notes
- Click any tag to add a color override for it
- Set the color and enable it
For nested tags, Flatnotes-Enhanced provides two input fields:
Parent field: projects
Child field: infrastructure
Result: #projects/infrastructure
To customize #work/projects/urgent:
-
Parent:
work -
Child:
projects/urgent
Each row has:
- Tag name input: Edit the tag path
- Color picker: Visual color selection
- Hex input: Enter color code directly
- Preview chip: Live preview showing tag with color
- Enabled toggle: Turn color on/off without deleting
- Delete button: Remove the override
#work → #0084FF (Blue) ✓ Enabled
#personal → #28A745 (Green) ✓ Enabled
#urgent → #DC3545 (Red) ✓ Enabled
#projects → #6F42C1 (Purple) ✓ Enabled
#archived → #6B7280 (Gray) ✓ Enabled
- Color psychology: Red for urgent, green for done, blue for work
- Consistency: Use the same colors across all notes
- Limit palette: 5-8 distinct colors is usually enough
- Accessible colors: Use colors with good contrast ratios
- Test both themes: Colors may look different in light/dark mode
Customize colors for Obsidian-style task markers.
Task icons are visual markers for different task states:
- [x] Completed task
- [ ] Pending task
- [>] In progress
- [!] Important/urgent
- [?] Question/uncertain
- [-] Cancelled- Go to Settings → Task Icons tab
- Toggle "Enable custom task icons" ON
- Task markers render as colored icons instead of plain text
- When OFF, markers display as plain text
[x],[>], etc.
For each available task marker:
- Icon visual: See the rendered icon
-
Syntax: Shows how to use it (e.g.,
- [x] text) - Label: Task type name (e.g., "Complete")
- Color picker: Click to choose color
- Hex input: Or enter color code directly
- Reset button: Revert to default color
| Marker | Label | Default Color | Use Case |
|---|---|---|---|
x |
Complete | Green | Done/finished |
[ ] |
Pending | Gray | Not started |
> |
In progress | Blue | Currently working |
! |
Important | Red | Urgent/critical |
? |
Question | Yellow | Uncertain/review |
- |
Cancelled | Gray | Abandoned/skipped |
< |
Deferred | Cyan | Postponed |
...and 10+ more Obsidian-compatible markers.
## My Tasks
- [x] Finish project proposal
- [ ] Review client feedback
- [>] Implement new feature
- [!] Fix critical bug
- [?] Clarify requirements
- [-] Old deprecated taskWith custom colors enabled, each marker displays as a colored icon.
- Click "Reset all colors" to revert all task icon colors to defaults
- Useful if you've customized many and want to start over
Create, edit, delete, and reorder saved search queries. Saved searches can be run directly from the Settings page or, optionally, from a collapsible section in the folder sidebar.
Each saved search stores:
- Name – a label for the query (e.g. “Work Notes”)
-
Query – the search string (e.g.
tags:work) - Sort order – optional default sort applied when the search runs
Actions available:
- Create – add a new saved search
- Edit – change the name, query, or sort order
- Delete – remove a saved search
- Run – execute the search immediately from Settings
- Reorder – drag and drop to change the order
To make saved searches available from the folder sidebar:
- Go to Settings → Preferences
- Toggle “Show saved searches in sidebar” ON
- Saved searches appear in a collapsible section below your folders
Note
Saved searches store the exact query string. The substring-search preference does not alter saved queries.
Account and behaviour settings, laid out in a two-column grid. Each row covers a related group of options.
- Display name – shown in the app header. Leave blank to use the default.
-
Avatar
-
Upload an Image:
- Click "Upload image" button
- Select an image file (JPG, PNG, GIF, etc.)
- Avatar displays as a circular profile picture in the header
- Click "Remove avatar" to delete it and revert to icon Tips:
- Small file size recommended (100KB or less)
- Square images work best (auto-cropped to circle)
- PNG for transparency, JPG for photos
-
Upload an Image:
-
TOTP QR code – only visible when
FLATNOTES_AUTH_TYPE=totp. Opens the authenticator setup QR code.
Set any note as your personal landing page when Flatnotes-Enhanced opens.
- Go to Settings → Preferences tab
- Toggle "Enable custom home note" ON
- Enter the note title (e.g.,
Daily DashboardorWelcome/Home) - Click "Save preferences"
- Next time you open Flatnotes-Enhanced, this note appears instead of the default home page
- Dashboard: Daily checklist, quick links to important projects
- Welcome: Introduction to your note system
- Weekly planner: Current week's overview
- Quick reference: Frequently accessed information
# 📋 My Daily Dashboard
## Today's Focus
- [ ] Check emails
- [ ] Team standup at 10am
- [ ] Review PR #42
- [ ] Update status report
## Quick Links
#urgent #meetings #projects
## Recent Important Notes
- [[Board Meeting Notes]]
- [[Q1 Planning]]Choose the reading width applied to notes:
| Option | Width |
|---|---|
| Normal | 999px |
| Wide | 1440px |
| Full Screen | 100% |
How notes appear in search results and list views.
| Option | Behavior |
|---|---|
| App default | Server-determined sort order |
| Last modified | Newest modified notes first |
| Title A–Z | Alphabetical by title |
| Title Z–A | Alphabetical descending |
| Relevance | Search score (most relevant first) |
Best choice depends on your workflow:
- Last modified: Good for active projects (always see what you just edited)
- Title: Good for reference notes (organized alphabetically)
- Relevance: Good for search-heavy workflows
When enabled:
- Buttons show both icon and text label (e.g., "Edit", "Delete", "Restore")
When disabled:
- Buttons show only icons (saves space, assumes you know the icons)
Best for:
- Enabled: New users, users with accessibility needs
- Disabled: Power users, mobile/smaller screens
When enabled:
- Click the eye icon next to notes in the sidebar
- A popup preview appears showing the note content
- Preview includes all formatting (highlights, callouts, tables, etc.)
When disabled:
- Eye icon doesn't appear
- Saves visual space in the sidebar
Toggle: in Preferences tab
- ON – saved searches appear in a collapsible section below folders in the folder sidebar
- OFF – saved searches are accessible only from Settings → Searches
Requires at least one saved search to be configured.
- ON – the app caches previously viewed notes and assets for read-only offline access. Requires the PWA to be installed from the browser.
- OFF – no API caching. The service worker still registers for installability.
When offline, an amber banner appears. Cache clears automatically when the feature is disabled. See the README’s PWA section for installation steps.
-
ON – YAML (
---) and TOML (+++) frontmatter blocks at the top of a note are stripped from the rendered view and preview popup. The file on disk is never modified. - OFF – frontmatter renders as-is.
Tags placed above the frontmatter (#pin, #archived) are preserved.
-
ON – search terms are automatically treated as substring queries (e.g.
alphbecomes*alph*). Works with tags, folders, saved searches, boolean operators, and quoted phrases. - OFF – exact-match behaviour (default).
Existing wildcards (*, ?) and tags: prefixes are preserved.
Two dropdowns control how dates appear throughout the app:
- Locale – language/region for date formatting (e.g. English GB, English US, German, French, Dutch, and others)
- Date Style – Short, Medium, or Long, with example previews shown for each option
- Live preview – a row below the dropdowns updates as you change locale or style, showing the current date in the selected format
Date formatting applies to search results, note lists, archive, trash, bookmarks, templates, and the Maintenance tab.
Rebrand your instance without touching code. Changes apply live across the app, including the login page.
| Option | Description |
|---|---|
| Name | Replaces the app name in the browser tab title and beside the logo |
| Accent colour | Drives buttons, links, highlights, and the tinted favicon |
| Logo | Replaces the default mark on login and home pages (SVG, PNG, JPG, WebP, GIF, ICO) |
| Favicon | Replaces the browser tab icon |
- Both set: the name displays beside the logo
- Name only: replaces the built-in wordmark
- Logo only: displays alone
| Variable | Effect |
|---|---|
FLATNOTES_BRAND_NAME |
Overrides the UI name. The Name field is disabled with an explanatory note. |
FLATNOTES_BRAND_ACCENT |
Overrides the UI accent colour. The Accent field is disabled. |
Logo and favicon are UI-only; there is no environment variable equivalent.
Click Reset to defaults to revert name, accent colour, logo, and favicon to stock Flatnotes-Enhanced.
Note
Logo and favicon are stored under .flatnotes/brand/ and served through public endpoints (/api/brand/logo, /api/brand/favicon) so they appear on the login page before authentication.
The Maintenance tab provides system information, backup management, and trash cleanup tools to keep your Flatnotes-Enhanced instance running smoothly.
Manage notes in the trash and configure automatic cleanup.
- In trash: Shows how many notes are currently in your trash
- Auto-delete: Displays the automatic cleanup interval (e.g., "Every 30 days") or "Manual only" if not configured
- Last cleaned: When trash was last automatically cleaned
Auto-delete is configured via the FLATNOTES_TRASH_DAYS environment variable:
# Delete trash older than 30 days automatically
FLATNOTES_TRASH_DAYS=30
# Disable auto-delete (manual only)
# (Don't set the variable)- Click "Empty trash now" button
- Enter the number of days:
- 0 = Delete all notes in trash immediately
- 30 = Delete only notes older than 30 days
- Click "Confirm"
- The operation is permanent
Quick overview of your note collection:
| Metric | Description |
|---|---|
| Notes | Total active notes (excluding archive/trash) |
| Archive | Notes in the _archive folder |
| Trash | Notes in the _trash folder |
| Attachments | Total file attachments in your system |
These numbers update when you click "Refresh".
Note
Security note (v1.18.2): Attachment and branding responses now include X-Content-Type-Options: nosniff. HTML, SVG, and XML attachments additionally receive a sandboxing Content-Security-Policy. Images, PDFs, text files, and downloads behave as before. SVG images embedded in notes render as before.
Three-column information display showing:
App Version
- Current version of Flatnotes-Enhanced
-
Update status:
- Offline - Never checked for updates (no internet)
- Up to date - You have the latest version
- Update available - Newer version available
- View release notes link (when update available)
- Last checked timestamp (when up to date)
Database
- Size of your SQLite database
- Database file path
- Shows "Not configured" if database is disabled
Project
- Flatnotes-Enhanced project information
- Built with ❤️ for better note-taking, by Bob W.
Automatically backup and restore your settings and preferences. Notes are not affected by backup/restore operations—they're stored as Markdown files.
✅ Backed up:
- All Settings (callouts, colors, headers, etc.)
- Preferences (display name, avatar, theme, etc.)
- Tag colors and customizations
- Task icon colors
- Home note configuration
❌ NOT backed up:
- Your notes (stored as .md files)
- Attachments (stored separately)
- Trash/Archive (not included in settings)
Automatic Backups:
- Created every midnight automatically
- Created on server startup
- Oldest backups automatically deleted (keep most recent 7 by default)
Manual Backup:
- Click "Backup now" button
- New backup is created immediately
- Appears in the backup list below
Configure how many backups to keep:
- Enter the number of backups to retain (1-30)
- Setting saves automatically
- Oldest backups are deleted when limit is exceeded
Default: 7 backups
Warning
Warning: Restore is permanent. A safety backup is created automatically before restoring.
- Find the backup in the list
- Click "Restore" button
- Type "RESTORE" to confirm (safety measure)
- Click "Confirm Restore"
- Preferences are restored
- Reload the page to apply restored preferences
Each backup contains:
-
Filename: Auto-generated (e.g.,
flatnotes_backup_startup_20260530_075127.db) - Size: How much space the backup takes
- Date: When the backup was created
-
Label: Type of backup:
- daily - Automatic midnight backup
- startup - Created on server startup
- manual - Created by clicking "Backup now"
Delete Old Backups:
- Click "Delete" on any backup
- Confirm deletion
- Backup is permanently removed
✅ Do this:
- Let automatic backups run (daily backups)
- Keep 5-7 backups for safety
- Test restore on non-critical instances first
- Create manual backup before major changes
❌ Avoid this:
- Deleting all backups (keep at least 2-3)
- Restoring from unknown/old backups without testing
- Assuming backups include your notes (they don't)
Backups Not Creating
- Check server disk space (backups need room)
- Verify database is enabled in settings
- Check server logs for errors
Restore Failed
- Backup file may be corrupted
- Try another backup from the list
- Verify restore confirmation text was typed correctly
Restored Settings Not Appearing
- Must reload the page after restore
- Check browser console for errors
- Try restore again from a different backup
Flatnotes-Enhanced automatically checks for updates when the Maintenance page loads.
Offline
- Server can't reach GitHub (no internet connection)
- Click "Refresh" to check again
Up to date
- You have the latest version
- Shows when version was last checked
Update available
- Newer version is available on GitHub
- Click "View release notes" to see what's new
- Follow the upgrade instructions for your setup (Docker/Manual)
- Click "Refresh" button at top-right of Maintenance page
- System checks GitHub for latest version
- Status updates with results
The Maintenance tab uses a responsive two-column design:
- Desktop (wide screens): Side-by-side layout shows Trash Manager + Content Summary
- Mobile (narrow screens): Stacks vertically for easier reading
- All sections responsive and touch-friendly
The theme picker (Navbar/hamburger → Theme) replaces the old Light/Dark/System cycle button. It offers 16 predefined themes grouped by family:
| Family | Themes |
|---|---|
| Default | Light, Dark, System |
| Dracula | Dracula, Dracula Alucard |
| Catppuccin | Latte, Frappé, Macchiato, Mocha |
| Gruvbox | Light, Dark |
| Nord | Nord |
| Solarized | Light, Dark |
| Tokyo Night | Tokyo Night, Storm, Light |
| One | One Dark, One Light |
- Click any theme to apply instantly; no page reload needed.
- Selection persists in
localStorage(key:fn_theme). - Old Light/Dark preferences migrate automatically on first load.
- A custom accent colour set in Branding overrides every theme's brand colour.
Note
The body.theme-* class applies the theme's CSS variables. Existing .dark-scoped styles continue to work.
Each tab has its own "Save" button. After customizing:
- Review your changes in the live preview
- Click the "Save [Feature]" button
- A status message appears:
- ✓ Green: Successfully saved
- ✗ Red: Save failed (check your connection)
- Settings persist across sessions
Use a unified color scheme across all customizations:
- Pick a primary color family (e.g., blues)
- Use complementary colors for contrasts
- Keep the color palette to 5-8 main colors
- Ensure sufficient color contrast (WCAG AA standard)
- Don't rely on color alone to convey information (use text labels)
- Test in both light and dark modes
- Simpler color schemes work better on small screens
- Avoid too many customizations—they may be harder to manage
- Test settings on your phone/tablet
Settings are not permanent:
- Try different color schemes
- Save, test, then adjust if needed
- Build your perfect setup over time
Problem: Clicked Save but settings reverted
Solutions:
- Check your internet connection
- Try saving again
- Refresh the page and modify again
- Check browser console for errors (F12 → Console tab)
Problem: Saved colors don't match what you saw
Cause: Your browser may have cached the old styles
Solution: Hard refresh the page (Ctrl+Shift+R or Cmd+Shift+R)
Problem: Looking for a specific customization
Solutions:
- Check the correct tab (use tab names as guide)
- Some features may be in different tabs than expected
Problem: Settings disappeared after logout
Reason: Settings are per-user (stored with your account)
Settings page has no dedicated shortcuts, but you can use:
-
Tab- Navigate between fields -
Shift+Tab- Navigate backwards -
Enter- Activate buttons -
Space- Toggle checkboxes
- Settings sync across instances: Not available (each instance has separate settings)
- Settings export/import: Not Planned!
- More theme presets: Not Planned!
- Font customization: Not Planned!
- Callout Blocks - Using callouts in your notes
- Tags System - Understanding tag colors in context
- Enhanced Editor - Using highlights in the editor
- Search & Filtering - How sort order affects search results