Settings & Customization

⚙️ Settings & Customization

Flatnotes-Enhanced gives you complete control over the look and feel of your note-taking experience. The Settings page is organized into six tabs, each handling a specific aspect of customization: callouts, appearance, advanced styling, tags, task icons, and personal preferences.

Accessing Settings

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 Tab

Callouts are highlighted blocks that draw attention to important information. They use Obsidian-style syntax and can be fully customized.

What Are Callouts?

Callouts are special formatted boxes with custom icons and colors:

> [!note]
> This is a note-type callout with an icon and custom color.

> [!warning]
> This is a warning — appears in the custom warning color.

> [!custom-type] Title
> Custom callout with your defined styling.

Built-in Callout Types

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.

Creating Custom Callouts

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
See the live preview chip update as you customize
Click "Save callouts" when done

Editing Existing Callouts

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

Using Custom Callouts in Notes

Once saved, use your custom callouts with the syntax:

> [!type]
> Your content here

> [!type] Optional Title
> Your content here

Example:

> [!pro]
> Use keyboard shortcuts to work faster!

> [!gotcha] Watch Out!
> This feature doesn't work with mobile devices.

Callout Design Tips

Use descriptive types: how-to, quick-win, heads-up are clearer than x, 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)

🎨 Appearance Tab

Customize how headings and text highlights appear in your notes.

Header Colors (H1-H6)

Make your headings more visually distinct with custom colors.

Enabling Header 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

Customizing Individual Headings

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

Design Best Practices

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)

Highlight Colors

Customize colors used when highlighting text in your notes.

Managing Highlight Colors

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)

Setting Default Highlight Color

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

Highlight Color Best Practices

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

🔧 Advanced Tab

Fine-tune how tables and blockquotes render in your notes.

Table Styling

Make tables in your notes more readable with custom header colors and row striping.

Enabling Table Styling

Go to Settings → Advanced tab
Toggle "Enable custom table styling" ON
Two options appear: header color and zebra striping

Table Configuration

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

Table Example

| 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)

Design Tips

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)

Quote Styling

Customize how blockquotes appear in your notes. Separate styling for light and dark themes.

Enabling Quote Styling

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)

Quote Configuration

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

Quote Styling Example

> 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: #1e40af at 20% opacity (subtle blue overlay)

Best Practices

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

🏷️ Tags Tab

Customize tag colors for the entire application.

Global Tag Color Control

Enabling Custom Tag Colors

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)

Default Tag Color

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

Per-Tag Color Overrides

When custom colors are enabled, you can assign specific colors to individual tags.

Adding Tag Colors

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

Nested Tag Support

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

Managing Tag Colors

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

Example Tag Color Setup

#work            → #0084FF (Blue)      ✓ Enabled
#personal        → #28A745 (Green)     ✓ Enabled
#urgent          → #DC3545 (Red)       ✓ Enabled
#projects        → #6F42C1 (Purple)    ✓ Enabled
#archived        → #6B7280 (Gray)      ✓ Enabled

Design Tips

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

🔲 Task Icons Tab

Customize colors for Obsidian-style task markers.

What Are Task Icons?

Task icons are visual markers for different task states:

- [x] Completed task
- [ ] Pending task
- [>] In progress
- [!] Important/urgent
- [?] Question/uncertain
- [-] Cancelled

Enabling Custom Task Icons

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.

Customizing Task Icon Colors

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

Available Task Icons

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.

Using Task Icons in Notes

## My Tasks

- [x] Finish project proposal
- [ ] Review client feedback
- [>] Implement new feature
- [!] Fix critical bug
- [?] Clarify requirements
- [-] Old deprecated task

With custom colors enabled, each marker displays as a colored icon.

Bulk Reset

Click "Reset all colors" to revert all task icon colors to defaults
Useful if you've customized many and want to start over

👤 Preferences Tab

Personal account and behavior settings.

Display Name

Field: Text input for your name
Display location: Shown in the app header/navbar
Leave blank: App shows default text
Use case: Multi-user scenarios or branded installations

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

Default Note Sort

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
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

Note Preview on Hover

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: Checkbox in Preferences tab

Button Labels

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

Custom Home Note

Set any note as your personal landing page when Flatnotes-Enhanced opens.

Setting a Custom Home Note

Go to Settings → Preferences tab
Toggle "Enable custom home note" ON
Enter the note title (e.g., Daily Dashboard or Welcome/Home)
Click "Save preferences"
Next time you open Flatnotes-Enhanced, this note appears instead of the default home page

Use Cases

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

Example Custom Home Note Setup

# 📋 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]]

🔧 Maintenance Tab

The Maintenance tab provides system information, backup management, and trash cleanup tools to keep your Flatnotes-Enhanced instance running smoothly.

Trash Manager

Manage notes in the trash and configure automatic cleanup.

Viewing Trash Status

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

Configuring Auto-Delete

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)

Emptying Trash Manually

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

Content Summary

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".

About & System Info

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.

💾 Preferences Backup & Restore

Automatically backup and restore your settings and preferences. Notes are not affected by backup/restore operations—they're stored as Markdown files.

What Gets Backed Up?

✅ 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)

Creating a Backup

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

Backup Retention

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

Restoring from Backup

⚠️ 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

Backup File Format

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"

Managing Backups

Delete Old Backups:

Click "Delete" on any backup
Confirm deletion
Backup is permanently removed

Backup Best Practices

✅ 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)

Troubleshooting Backups

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

Version Check

Flatnotes-Enhanced automatically checks for updates when the Maintenance page loads.

Update Status

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)

Checking for Updates Manually

Click "Refresh" button at top-right of Maintenance page
System checks GitHub for latest version
Status updates with results

Two-Column Layout

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

💾 Saving Settings

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

Best Practices & Tips

Consistent Theme

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

Accessibility

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

Mobile-Friendly

Simpler color schemes work better on small screens
Avoid too many customizations—they may be harder to manage
Test settings on your phone/tablet

Iteration

Settings are not permanent:

Try different color schemes
Save, test, then adjust if needed
Build your perfect setup over time

Troubleshooting

Changes Not Saving

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)

Colors Look Different Than Preview

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)

Can't Find a Setting

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

Saved Settings Reset

Problem: Settings disappeared after logout

Reason: Settings are per-user (stored with your account)

Keyboard Shortcuts

Settings page has no dedicated shortcuts, but you can use:

Tab - Navigate between fields
Shift+Tab - Navigate backwards
Enter - Activate buttons
Space - Toggle checkboxes

Limitations & Roadmap

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!