notesbase

Vibe coded self-hosted notes app.

notesbase overview
Rich text editor with multiple formats

Why I built this

I wanted a shared notes app I could self-host without paying per seat or trusting someone else’s cloud with my data. Notion is great but everything lives on their servers. Obsidian is local-first but multi-user sync is a pain. notesbase is the middle ground: simple to run, actually multi-user, with client-side encryption built into the login flow.

notesbase Notion Obsidian

Self-hosted

✓

✗

✓ (local only)

Multi-user

✓

✓ (paid/seat)

✗

Client-side encryption

✓

✗

✗

Setup complexity

docker compose up

SaaS

Complex sync

Open source

✓

✗

✗

Features

  • Hierarchical pages with custom icons

  • Rich editor - headings, code blocks, tables, callouts, lists, file uploads, inline PDFs, [[page mentions]]

  • Tags & full-text search

  • Client-side AES-GCM encrypted pages (keyed to your account password, server never sees plaintext)

  • Multi-user with admin role; optional registration disable

  • File storage via S3/MinIO

  • Plugin API with scoped API keys (pages:read, pages:write, tags:*, files:*)

Quick Start

git clone https://github.com/pljeske/notesbase
cd notesbase
cp .env.example .env
docker compose up

Open http://localhost:3000 and register. First account becomes admin.

Stack

  • Go (Gin, pgx, golang-migrate)

  • React + TypeScript + Vite + TipTap + Zustand

  • PostgreSQL

  • MinIO (S3-compatible)

  • Docker Compose / Helm

Plugin API

Create an API key in Settings, then authenticate with Authorization: Bearer nbp_<key>.

# List pages
curl -H "Authorization: Bearer nbp_..." http://localhost:8080/api/v1/plugin/pages

# Create a page
curl -X POST -H "Authorization: Bearer nbp_..." \
     -H "Content-Type: application/json" \
     -d '{"title":"My page","content":{}}' \
     http://localhost:8080/api/v1/plugin/pages

Available scopes: pages:read, pages:write, tags:read, tags:write, files:read, files:write. Encrypted pages are read-only via the API (the server never holds the key).

Roadmap

  • Favorites / pinned pages

  • Backup & restore

  • Dark mode

  • MCP server for querying notes

User Guide

A self-hosted notes application with rich text editing, hierarchical pages, tags, encryption, and file uploads.

.1. Getting Started

.1.1. Creating an Account

Navigate to the Notesbase URL and click Sign up on the login page. The first user to register automatically becomes an administrator. Subsequent registrations create regular user accounts.

Registration may be disabled by your administrator. Contact them if you cannot access the sign-up page.

.1.2. Logging In

Enter your email and password on the login page and click Sign in. If you have forgotten your password, click Forgot password? to receive a reset link by email.

.1.3. The Interface

After logging in you will see two main areas:

  • Sidebar (left) — page tree, search, tags, and trash

  • Editor (right) — the content area for the selected page

The header bar across the top contains breadcrumb navigation, save status, page actions, and account controls.

.2. Pages

.2.1. Creating Pages

Use the + button at the top of the sidebar to create a new root-level page. To create a subpage nested under an existing page, open that page’s context menu (⋯) and choose Add subpage.

.2.2. Page Tree

All pages are displayed as a collapsible hierarchy in the sidebar. Click the chevron icon (►) next to a page to expand or collapse its children. The currently active page is highlighted.

Pages with encryption enabled display a lock icon (🔒) next to their title.

.2.3. Reordering Pages

Click and hold the drag handle (⠿, the six-dot icon) to the left of a page title, then drag it to a new position. Reordering is supported within the same parent level.

.2.4. Context Menu

Hover over any page in the sidebar and click ⋯ to open its context menu. Available actions:

Action Description

Add subpage

Creates a new child page nested under this one.

Duplicate

Creates a copy of the page (not nested under the original).

Move to Trash

Soft-deletes the page; it can be restored from the Trash section.

.2.5. Page Icons

Click the icon area to the left of the page title in the editor to open the icon picker. Choose an emoji or icon and optionally select a color. The icon appears in the sidebar, breadcrumbs, and search results. To remove an icon, open the picker and select the clear option.

.2.6. Breadcrumbs

The breadcrumb bar at the top of the editor shows the full path from the root to the current page. Click any ancestor in the breadcrumb to navigate to it.

.3. Editing Content

page view

.3.1. The Editor

Click into the content area below the page title to begin writing. The editor auto-saves your changes with a short delay after you stop typing. The current save state is shown in the header:

  • Saving… — a save is in progress

  • Saved — the last save was successful

  • Save failed — an error occurred; check your connection

.3.2. Slash Commands

Type / anywhere in the editor to open the block insertion menu. Type to filter the list, then click or press Enter to insert a block.

Slash menu
Table 1. Available block types
Block Description

Heading 1 / 2 / 3

Section headings at three levels.

Bullet list

Unordered list items.

Numbered list

Ordered (numbered) list items.

Blockquote

Indented quotation block.

Code block

Syntax-highlighted code (see Code Blocks).

Table

3×3 table (see Tables).

Divider

Horizontal rule separating content sections.

Image

Upload an image from your device (see Images).

PDF

Upload a PDF for inline preview (see PDFs).

File

Upload any file as a downloadable attachment (see Files).

Info / Warning / Tip callout

Highlighted callout block for notices and tips.

Page mention

Inline link to another page (see Page Mentions).

.3.3. Text Formatting

Select any text to reveal the formatting toolbar. Available options:

Format Shortcut

Bold

Ctrl+B / ⌘+B

Italic

Ctrl+I / ⌘+I

Underline

Ctrl+U / ⌘+U

Strikethrough

—

Inline code

—

Link

Paste a URL or click the link icon to enter one

.3.4. Code Blocks

Insert a code block via /code. Click the language label at the top-right of the block to select from 24+ supported languages including Python, JavaScript, TypeScript, Go, Rust, Java, C++, SQL, and more. Syntax highlighting is applied automatically.

.3.5. Tables

Insert a table via /table. A 3×3 grid is created by default. Right-click a cell or use the table toolbar to:

  • Add or remove rows and columns

  • Delete the table

.3.6. Images

Images can be added in three ways:

  • Type /image and upload a file from your device

  • Drag an image file from your file manager and drop it into the editor

  • Paste an image from your clipboard (Ctrl+V / ⌘+V)

After inserting an image, drag the resize handles on its edges to adjust its dimensions.

.3.7. PDFs

Type /pdf to upload a PDF file. The PDF renders as an inline preview that can be expanded or collapsed. Click Open in new tab to view the full document in your browser.

.3.8. Files

Type /file to upload any file type as a downloadable attachment. A download link is inserted into the page.

.4. Page Mentions and Backlinks

.4.1. Page Mentions

Type [[ anywhere in the editor to open the page mention autocomplete. Start typing the page title to filter results, then click or press Enter to insert the link. The mention appears as an inline chip with the page title.

Mentioning a page automatically creates a backlink in the target page.

.4.2. Backlinks

The Backlinks panel at the bottom of the editor lists all pages that contain a mention of the current page. Click any backlink entry to navigate to that page.

.5. Tags

.5.1. Adding Tags to a Page

Click the tag icon in the page toolbar (top-right area) to open the tag picker. Check the boxes next to tags you want to assign. Tags are shown as coloured badges below the page title.

.5.2. Creating Tags

In the tag picker, type a new tag name in the search field and click Create tag. A color is assigned automatically; you can change it later.

.5.3. Managing Tags

Click Manage in the sidebar Tags section to open the tag management modal. From here you can:

  • Rename a tag

  • Change its color (choose from 16+ predefined colors)

  • Delete a tag

Deleting a tag removes it from all pages it is assigned to.

.5.4. Browsing by Tag

Click any tag in the sidebar Tags section to see all pages assigned to that tag. Each page shows its title, icon, and last-updated date.

.6. Search

Click the search bar at the top of the sidebar or press / to focus it. Results appear as you type (with a short debounce delay).

Use ↑ and ↓ to navigate results, Enter to open the selected page, and Escape to close.

Encrypted pages are excluded from search results.

.7. Encryption

.7.1. Encrypting a Page

Click the lock icon in the page toolbar to toggle encryption. Once enabled, the page content is encrypted using your account password. A badge reading Encrypted · not searchable appears in the toolbar.

.7.2. Unlocking Encrypted Pages

If your session has expired, click the lock icon in the main header to re-enter your account password and unlock all encrypted pages for the current session.

.7.3. Removing Encryption

Click the lock icon in the page toolbar and confirm when prompted. The page content will be decrypted and stored as plain text.

Encrypted pages are not indexed for search. Use encryption only for content that requires it.

.8. Trash

.8.1. Moving Pages to Trash

Open a page’s context menu in the sidebar and choose Move to Trash. The page is soft-deleted and no longer appears in the main tree.

.8.2. Restoring Pages

Expand the Trash section at the bottom of the sidebar. Click Restore next to a page to move it back to the root of the page tree.

.8.3. Permanently Deleting Pages

Click the delete icon next to a trashed page and confirm the second click. Permanent deletion cannot be undone.

.9. Export

.9.1. Exporting a Single Page

Click the export icon in the page toolbar to open the export dialog. Choose a format and download the file.

.9.2. Exporting All Pages

Click the export icon at the top of the sidebar to export your entire workspace. A zip file is not produced; each page is exported as a separate download.

.9.3. Export Formats

Format Description

Markdown (.md)

Plain-text Markdown with title, tags, and content.

HTML (.html)

Styled HTML representation of the page.

JSON (.json)

Structured data including all page properties.

.10. API Keys

Navigate to Settings → API Keys to manage programmatic access.

.10.1. Creating a Key

  1. Click Create API key.

  2. Enter a descriptive name.

  3. Select the scopes (permissions) the key should have.

  4. Click Create.

Copy the secret key immediately after creation — it is shown only once.

.10.2. Using a Key

Include the key in the Authorization header of API requests:

Authorization: Bearer nbp_<your-key>

.10.3. Deleting a Key

Click the delete icon next to a key and confirm to revoke it immediately.

.11. Admin Panel

The Admin Panel is accessible from the header for administrator accounts only.

.11.1. User Management

The Users table lists all registered accounts with their name, email, role, and status.

Action Description

Change role

Use the dropdown to promote a user to admin or demote to user. You cannot change your own role.

Disable / Enable

Prevent a user from logging in without deleting their account.

.11.2. Registration Settings

Toggle Allow new user registration to control whether the sign-up page is accessible. When disabled, new users cannot create accounts.

.12. Keyboard Shortcuts

Shortcut Action

/

Open slash command menu in the editor

\[\[

Open page mention autocomplete

Ctrl+B / ⌘+B

Bold

Ctrl+I / ⌘+I

Italic

Ctrl+U / ⌘+U

Underline

Ctrl+V / ⌘+V

Paste (images paste directly into the editor)

↑ / ↓

Navigate search or slash command results

Enter

Confirm selected search result or slash command

Escape

Close search, slash command menu, or modals