Flatnotes-Enhanced

A professional-grade, feature-rich fork of Flatnotes.

Flatnotes-Enhanced elevates the original Flatnotes into a powerful, customizable, and user-friendly note-taking application. Designed for professionals and enthusiasts, it offers advanced organization, visual customization, and a seamless user experience—all while maintaining simplicity and performance.

Disclaimer: This is a community fork with limited support. For basic Flatnotes issues, please refer to the original Flatnotes documentation.

---

📖 Table of Contents

• Key Features
• Pages & Views
• Settings Configuration
• Screenshots
• Getting Started
• Building the Docker Image
• Manual Installation
• Environment Variables
• Known Issues & Roadmap
• License
• Acknowledgments

---

🆕 What's New in v1.4.1

• Attachment System Overhaul – 40+ file types supported with proper icons and colours (documents, spreadsheets, archives, audio, video, code, and more)
• Attachments Page Redesign – Search, filter by usage (All/In use/Unused), sort by name/category/size/usage, and category badges

View full changelog

---

✨ Key Features

📁 Advanced Organization

Feature	Description
Dual Sidebars	Separate sidebars for folders and tags, with smooth toggle functionality.
Folder Management	Full nested folder support with auto-creation from note titles.
Bulk Operations	Select multiple notes and move them to existing or new folders.
Drag & Drop	Intuitive drag-and-drop for moving notes between folders.
Smart Counters	Real-time note counts for folders and tags.
Duplicate Notes	Copy one or more notes to any folder; originals remain untouched. Smart naming resolves conflicts automatically (Report (copy), Report (copy 2), etc.).
Bulk Delete	Soft-delete multiple notes at once from the sidebar. Notes go to _trash and can be restored later.

🏷️ Tag System

Feature	Description
Nested Tags	Hierarchical tag support (e.g., #projects/ux).
Custom Colors	Assign unique colors to tags with live preview.
Tag Sidebar	Searchable tag list with collapse/expand functionality.
Visual Chips	Pill-shaped tags with nested path display (e.g., projects › ux).

📝 Enhanced Editor

Feature	Description
Custom Highlights	Colored text highlighting with picker and default colors.
Search & Replace	Full search/replace functionality (Ctrl+H).
Smart Autocomplete	Real-time suggestions for tags, callouts, variables, and task icons.
File Attachments	Support for 40+ file types – documents (DOCX, ODT, TXT), spreadsheets (XLSX, CSV), presentations (PPTX), archives (ZIP, RAR, 7Z), audio (MP3, WAV, FLAC), video (MP4, MKV, MOV), code files (JS, PY, HTML, JSON), and more. Proper icons and colours for each category.
PDF Preview	In-browser preview for attached PDFs.

🎨 Visual Customization

Feature	Description
Callout Blocks	Obsidian-style callouts (> [!note]) with custom colors and icons.
Header Colors	Custom colors for H1-H6, with per-header enable/disable.
Table Styling	Custom header colors and zebra striping.
Quote Styling	Custom border and background colors (separate for light/dark mode).
Task Icons	Obsidian-style task markers (- [>]) with custom colors.
Nested Tasks	Collapsible nested tasks support with chevron marker.
Tag Colors	Per-tag color overrides with global enable/disable.
Custom Task Icons	Customize colors for Obsidian-style task markers (see Settings page).

👁️ Preview System

Feature	Description
Note Popup Preview	Click the eye icon to preview notes without opening.
Full Rendering	Previews render callouts, tags, tables, and highlights.
Smart Positioning	Popup automatically positions near the clicked button.
Toggle Option	Enable/disable preview in settings.

🗑️ Note Management

Feature	Description
Soft Delete	Notes move to _trash folder; not permanently deleted.
Trash Page	Browse, restore, or permanently delete trashed notes.
Archive	Move notes to _archive folder with automatic #archived tag.
Bookmarks	Pin important notes with #pin tag.
Templates	Save and reuse note templates from _templates folder.

🔄 Navigation & UI

Feature	Description
Back/Forward	Navigate through recently viewed notes.
Home Button	Always-visible home button for quick access.
Mobile Optimized	Responsive design for all screen sizes.
Theme Toggle	Light/Dark/System theme with automatic OS detection.
Preferences	Display name, avatar, default sort, note preview toggle, button label toggle, custom home note.

💾 Data & Storage

Feature	Description
SQLite Database	Persistent storage for user preferences and settings.
Metadata Sidecars	Creation/modification dates stored in .meta.json files.
JSON Migration	Automatic migration from legacy JSON settings.
Multi-User Ready	Database schema supports multiple users.
Multi-Instance Support	Run two or more Flatnotes-Enhanced instances on the same server.

🔐 Authentication

Feature	Description
TOTP Support	Two-factor authentication with QR code setup (on Login page).
Multiple Auth Types	None, Read-Only, Password, or TOTP.

---

📋 Pages & Views

Page	Purpose
Home	Quick access to recently modified notes.
Search	Full-text search with sorting options.
Note Editor	WYSIWYG/Markdown editing with all enhancements.
Folders	Browse and manage notes by folder structure.
Tags	Browse and manage notes by tags.
Archive	View and restore archived notes.
Trash	Manage soft-deleted notes.
Bookmarks	View all pinned notes.
Templates	Manage note templates.
Attachments	Browse, search, filter, and sort file attachments. Category badges show file types at a glance.
Settings	Full customization interface.

---

⚙️ Settings Configuration

Tab	Configuration Options
Callouts	Create custom callout types with icons and colors.
Appearance	Header colors, highlight colors.
Advanced	Table styling, quote styling.
Tags	Global tag colors + per-tag overrides.
Task Icons	Custom colors for task markers.
Preferences	Display name, avatar, default sort, note preview toggle, button label toggle, custom home note.

---

📸 Screenshots

Note: Some Screenshots of the Enhanced Features

Feature	Screenshot
Flatnotes-Enhanced Home Page
Folder sidebar with drag & drop
Tag sidebar with color chips
Note popup preview
Settings page (Callouts tab)
Settings page (Appearances tab)	,
Settings page (Advanced tab)	,
Settings page (Tags tab)	,
Settings page (Task Icons tab)	,
Settings page (Account tab)

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• Node.js 20+
• (Optional) Docker for containerized deployment

---

🐳 Building the Docker Image

If you prefer to use Docker, you can build the image yourself:

# Clone the repository
git clone https://github.com/BobWs/flatnotes-enhanced.git
cd flatnotes-enhanced

# Build the Docker image
docker build -t flatnotes-enhanced:latest .

# Run the container
docker run -d \
  --name flatnotes-enhanced \
  -p 8080:8080 \
  -v "$(pwd)/data:/data" \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  flatnotes-enhanced:latest

🐳 Docker

Supports linux/amd64 and linux/arm64 (Raspberry Pi, Apple Silicon).

docker pull dockerbobw/flatnotes-enhanced:latest
docker run -d \
  --name flatnotes-enhanced \
  -p 8080:8080 \
  -v ./data:/data \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  dockerbobw/flatnotes-enhanced:latest

---

📦 Manual Installation

Step 1: Install Dependencies

Backend (Python):

# Install pipenv if you don't have it
pip install pipenv

# Install dependencies
pipenv install

Frontend (Node.js):

# Install dependencies
npm ci

Step 2: Build the Frontend

npm run build

Step 3: Run the Server

# Using pipenv
pipenv run uvicorn server.main:app --host 0.0.0.0 --port 8080

# Or using Python directly
python -m uvicorn server.main:app --host 0.0.0.0 --port 8080

Step 4: Access Flatnotes-Enhanced

Open your browser and navigate to http://localhost:8080

---

🌍 Environment Variables

Variable	Description	Default
FLATNOTES_AUTH_TYPE	Authentication type (none, read_only, password, totp)	password
FLATNOTES_USERNAME	Username for password authentication	(required)
FLATNOTES_PASSWORD	Password for password authentication	(required)
FLATNOTES_SECRET_KEY	Secret key for JWT tokens	(required)
FLATNOTES_PATH	Path to notes storage	/data
FLATNOTES_HOST	Host to bind the server to	0.0.0.0
FLATNOTES_PORT	Port to bind the server to	8080
ENABLE_DATABASE	Enable SQLite database for settings	true
DATABASE_PATH	Path to SQLite database file	/data/.flatnotes/flatnotes.db
DATABASE_ECHO	Enable database SQL logging	false
LOGLEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO

---

🐛 Known Issues & Roadmap

Current Status

• ✅ All other features – stable

Tags

• latest – newest version (multi-arch: linux/amd64 + linux/arm64)
• v1.4.1 – Attachment System Overhaul + Attachments Page redesign (search, filter, sort)
• v1.4.0 – New: Custom Home Note + Preferences tab redesign
• v1.3.0 – Multi-Instance Support (run two or more Flatnotes-Enhanced instances on the same server)
• v1.2.0 – Button Label Toggle & UI Polish
• v1.1.0 – Duplicate notes + bulk delete
• v1.0.2 – multi-arch support (ARM64)
• v1.0.1 – bug fix release (amd64 only)
• v1.0.0 – first stable release (amd64 only)

Multi-Instance Setup

Running separate instances for work and personal notes? Flatnotes-Enhanced fully supports multi-instance deployment on the same server.

• Unique storage keys – No session bleed, no cache conflicts
• Works with TOTP – Each instance has its own 2FA secret
• Any reverse proxy – Nginx, Caddy, Nginx Proxy Manager

📖 Full multi-instance guide

Custom Home Note

Want to land on your dashboard, weekly planner, or project overview every time you open the app? Set any note as your personal start page.

• Loads on app start — no extra click needed
• Home button always navigates there — so does Ctrl+Alt+H
• Works with folder paths — e.g. Work/Weekly or Projects/Dashboard
• Opt-in — users who prefer the default quick-access home page are unaffected

Setup: Settings → Preferences → Custom home note → toggle on → enter note title → Save.

---

Future Features

• Wikilink Popup Modal - planned!
• Modal table editor – planned!
• Spreadsheet in notes – planned!
• Auto-delete trash after N days
• Multi-user support
• Automatic database backup

---

📄 License

This project is a fork of Flatnotes and retains its original license.

---

🙏 Acknowledgments

• Original Flatnotes by Dullage
• Toast UI Editor by NHN Cloud
• All contributors and testers

---

Built with ❤️ for better note-taking.