1. Project Overview

Dedicated to building a secure and extensible personal knowledge base that supports notes, to-do lists, file management, and other features to help you organize and manage all your data.

xnote is a lightweight note-taking system designed for personal use. It provides various data management capabilities and aims to free individuals from information overload. Its main features include:

• Rich data management capabilities, supporting multiple note formats and file management features.
• Provides commonly used tools by default, along with extensibility that allows users to develop various plugins to meet their needs.
• Cross-platform support for Windows, Mac, and Linux. It can be deployed on cloud services or run locally.
• 100% control over your data, with support for multiple database environments.
• Supports small-scale multi-user environments. Use with caution in commercial scenarios involving multiple users.

Currently, xnote is positioned as a small note-taking product for personal use and will not focus on the following areas:

• Large-scale multi-user support
• Multi-user collaboration features

If you love technology, enjoy experimenting, need versatile data processing capabilities, and want complete control over your document data, this product is worth trying. Feedback is welcome.

2. Open Source License

Licensed under GPL-3.0

3. Screenshots

4. Feature Overview

Main Functions

Note Management

• Multiple formats: Markdown / Tables / Albums / Lists
• Organization: Manage documents using notebooks, tags, and priorities.
• Sharing: On a note's detail page, click Share in the More dropdown menu to share the article with users who are not logged in.
• Priority Management: Pinning and archiving features.
• Backup: Note revision history.
• Search: Supports searching across the entire knowledge base and within individual projects.
• Comments: Supports comments from logged-in users.
• Access Statistics: Track recent and frequently accessed items.
• Other Document Tools

File management

• Multiple Views: List and Grid.
• File Operations: Upload, download, create, delete, rename, move, and other file operations.
• File Tools: Code editor, text reader, binary viewer, file content search, and more.
• Large File Support: File downloads support resumable transfers, and uploading extremely large files is supported (tested with 1 GB files).
• Extensibility: Supports plugin development and extensions.

Toolbox

• Python Documentation (pydoc)
• Text Processing (text comparison, code generation, password generation)
• Encoding and Decoding Tools (Base64, MD5, number base conversion, etc.)
• Barcode and QR Code Generator
• Image Processing (merging, splitting, grayscale conversion)
• Provides extensibility, allowing developers to create their own plugins.

System Extensions

Since everyone's needs are different, a single system can hardly meet all requirements. Developers can write their own plugins to extend system functionality as needed. For details, refer to the Plugin Extensions documentation.

The specific features are as follows:

• Plugins can listen for system messages, including five types: notes, reminders, files, time, and system.
• Plugins can use the category property to specify categories, which are displayed in the option menus of features such as notes, files, and system settings.
• Plugins can be created using templates.

5. Tech Stack

System architecture

Layered Architecture

Program Directory Structure

|-- app.py          # Application entry point
|-- core/
|   |-- xconfig.py      # Application configuration
|   |-- xmanager.py     # Handler manager, responsible for module loading, URL registration, and scheduled task triggering
|   |-- xauth.py        # Access control
|   |-- xtables.py      # Database table schema
|   |-- xtemplate.py    # Rendering interface for the view layer
|   \-- autoreload.py   # Hot reloading when scripts change, mainly for debugging; can be disabled in production
|
|-- xutils/         # Collection of utility classes
|-- lib/            # Third-party libraries, added to sys.path at application startup
|-- config/         # System configuration directory
|   |-- file/       # File configuration
|   |-- lang/       # Multilingual configuration
|   \-- template/   # Template configuration
|
|-- handlers/       # HTTP request handlers, where most functionality is implemented
|   |-- api/        # System APIs that return JSON for pages, scheduled tasks, and search operations
|   |-- system/     # System functionality
|   |-- note/       # Note functionality
|   |-- fs/         # File functionality
|   |-- tools/      # Tools directory
|   |-- plugins/    # Plugins directory
|   \-- ...         # Other directories
|-- static/         # Static files
\-- tests/          # Test cases

Data Directory Structure

|-- files/     # Uploaded files
|   \-- user01 # User directory, named after the username; supports multiple users
|       |-- upload   # Uploaded files directory, organized into subdirectories by date, such as 2019/01/
|       |-- gallery  # Gallery files
|
|-- backup/    # Backup directory
|-- scripts/   # Scripts directory
|-- storage/   # Application storage directory
|-- db/        # Database directory
|-- log/       # Log directory
|-- tmp/       # Temporary files
\-- trash/     # Recycle Bin

Development Frameworks / Software Libraries

For specific versions, see requirements.txt.

• webpy (modified version, built into xnote)
• tornado template (modified version, built into xnote)
• sqlite3 (file-based database included with Python)
• wsgidav Provides WebDAV functionality for mounting network drives
• psutil (optional, collects system runtime statistics)
• comtypes (optional, used to call the Microsoft Speech API)

Frontend Dependencies

• jquery JavaScript base library
• layer Web popup component
• marked Markdown parser
• codemirror Code editor
• jexcel Web spreadsheet
• font-awesome Icon library
• art-template Template engine
• vue2 MVVM framework
• qrcode QR code generator
• csv.js CSV file parser
• jsdiff Text comparison

Developing a New Module

Add a Python program to the handlers directory, for example, test.py.

class MyHandler:    
    def GET(self):
        return "success"

class Handler2:
    def GET(self):
        return "handler2"

# URL routing rules, supporting multiple configurations
xurls = (
    r"/test", MyHandler,
    r"/handler2", Handler2
)

# Start xnote, then open localhost:1234/test in your browser to see success

Installation & Running

Install Dependencies

• Install Python (Python 3 is recommended; Python 2.7 is no longer maintained).
• Install the required packages. On Mac/Linux, run: python -m pip install -r config/requirements.txt. On Windows, run: python -m pip install -r config/requirements.win.txt.

Configuration and Startup

The default configuration file is located at:

config/boot/boot.default.properties. For details about specific features, refer to the configuration comments.

# Specify a custom configuration file
python3 app.py --config config/boot/custom-name.properties

If you do not change the port number, you can start using the application by opening [http://localhost:1234/](http://localhost:1234/) in your browser after startup. The initial administrator account is admin, and the default password is 123456.

Deployment on Cloud Service Platforms

• Sina SAE TODO
• CentOS - Baidu BAE

Compatibility Issues

If startup fails after updating an installation of an older version, refer to Database Migration or check the Issues section. If the problem persists, you can submit a new Issue.