A simple, self-hosted app for your checklists and notes.

Tired of bloated, cloud-based to-do apps? rwMarkable is a lightweight alternative for managing your personal checklists and notes. It's built with Next.js 14, is easy to deploy, and keeps all your data on your own server.

Join the discord server for more info

Clean, intuitive interface for managing your checklists and tasks.

Heavily customisable themes.

Rich text editor for notes and beautiful theme customization.

• Features
• Tech Stack
• Getting Started
  • Docker Compose (Recommended)
  • Initial Setup
  • Local Development (Without Docker)
• Data Storage
• Updating
  • Docker Compose
  • Manual
• API
• Shortcuts
• Single Sign-On (SSO) with OIDC
• Custom Themes and Emojis

• Checklists: Create task lists with drag & drop reordering, progress bars, and categories. Supports both simple checklists and advanced task projects with Kanban boards and time tracking.
• Rich Text Notes: A clean WYSIWYG editor for your notes, powered by TipTap with full Markdown support and syntax highlighting.
• Sharing: Share checklists or notes with other users on your instance, including public sharing with shareable links.
• File-Based: No database needed! Everything is stored in simple Markdown and JSON files in a single data directory.
• User Management: An admin panel to create and manage user accounts with session tracking.
• Customisable: 14 built-in themes plus custom theme support with custom emojis and icons.
• API Access: Programmatic access to your checklists and notes via REST API with authentication.

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• State: Zustand
• Editor: TipTap
• Deployment: Docker

The recommended way to run rwMarkable is with Docker.

1. Create a docker-compose.yml file:

   📖 For more information about how the docker compose file works and what these variables do, please read howto/DOCKER.md

   services:
     rwmarkable:
       image: ghcr.io/fccview/rwmarkable:latest
       container_name: rwmarkable
       user: "1000:1000"
       ports:
         - "1122:3000"
       volumes:
         - ./data:/app/data:rw
         - ./config:/app/config:ro
         - ./cache:/app/.next/cache:rw
       restart: unless-stopped
       #platform: linux/arm64
       environment:
         - NODE_ENV=production
         #- HTTPS=true
         #- SERVE_PUBLIC_IMAGES=yes
         #- SERVE_PUBLIC_FILES=yes
         #- SSO_MODE=oidc
         #- OIDC_ISSUER=<YOUR_SSO_ISSUER>
         #- OIDC_CLIENT_ID=<YOUR_SSO_CLIENT_ID>
         #- APP_URL=https://your-rwmarkable-domain.com
         #- OIDC_CLIENT_SECRET=your_client_secret
         #- SSO_FALLBACK_LOCAL=true
         #- OIDC_ADMIN_GROUPS=admins

2. Create the data directory and set permissions:

   mkdir -p data/users data/checklists data/notes data/sharing cache
   sudo chown -R 1000:1000 data/
   sudo chown -R 1000:1000 cache/

   Note: The cache directory is optional. If you don't want cache persistence, you can comment out the cache volume line in your docker-compose.yml.

3. Start the container:

   docker-compose up -d

The application will be available at http://localhost:1122.

On your first visit, you'll be redirected to /auth/setup to create your admin account if SSO is disabled, otherwise you'll be prompted to sign in via your choosen SSO provider.

Once that's done, you're ready to go! First user will be admin by default.

If you want to run the app locally for development:

1. Clone & Install:

   git clone <repository-url>
   cd checklist
   yarn install

2. Run Dev Server:

   yarn dev

   The app will be running at http://localhost:3000.

rwMarkable uses a simple file-based storage system inside the data/ directory.

• data/checklists/: Stores all checklists as .md files.
• data/notes/: Stores all notes as .md files.
• data/users/: Contains users.json and sessions.json.
• data/sharing/: Contains shared-items.json.
• data/settings.json: App settings (name, description, custom icons).
• data/uploads/app-icons/: Custom uploaded app icons.

Make sure you back up the data directory!

Pull the latest image and restart your container.

docker-compose pull
docker-compose up -d

If you're running from source, pull the latest changes and rebuild.

git pull
yarn install
yarn build
yarn start

rwMarkable supports GitHub Flavored Markdown (GFM) and some custom syntax for complex functionality.

📖 For the complete MARKDOWN documentation, see howto/MARKDOWN.md

rwMarkable includes a REST API for programmatic access to your checklists and notes. This is perfect for:

• Automation: Create tasks from external systems
• Integrations: Connect with other tools and services
• Scripts: Automate repetitive tasks
• Dashboards: Build custom interfaces

📖 For the complete API documentation, see howto/API.md

rwMarkable supports a wide range of keyboard shortcuts to help you navigate and edit more efficiently without leaving the keyboard. They are divided into two main categories: global shortcuts that work anywhere in the app, and editor-specific shortcuts that work when you are writing a note.

📖 For the complete SHORTCUTS documentation, see howto/SHORTCUTS.md

rwMarkable supports any OIDC provider (Authentik, Auth0, Keycloak, Okta, etc.)

📖 For the complete SSO documentation, see howto/SSO.md

You can easily add custom themes and emojis by creating configuration files in the config/ directory. These will be automatically loaded and merged with the built-in themes and emojis.

📖 For the complete customisation documentation, see howto/CUSTOMISATIONS.md

I would like to thank the following members for raising issues and help test/debug them!

fruiz1972	seigel	mariushosting	Isotop7	bluegumcity
IGOLz	floqui-nl	davehope	Sku1ly	ItsNoted
red-bw	kn0rr0x	mroovers	Ryderjj89	spaghetti-coder
hurleyy	schneider-de-com	zolakt	Justus0405

This project is licensed under MIT License.

For issues and questions, please open an issue on the GitHub repository.