notd: a simple outliner on notd

Frontend Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Get up and running with notd’s powerful frontend features in minutes. This guide covers the essential features you need to know to be productive immediately.

First Steps

1. Understanding the Interface

When you first open notd, you’ll see:

Sidebar (left) - Navigation, search, and quick access
Main area (center) - Your notes and content
Today’s date - notd starts with today’s journal page

2. Create Your First Note

Core Features

Mon, 01 Jan 0001 00:00:00 +0000

Rich Text Editing with Markdown

notd uses Markdown for formatting notes with live preview capabilities. The editor supports:

Headers using # ## ###
Lists with - or 1.
Links using [text](url)
Code blocks with triple backticks
Emphasis with *italic* and **bold**

Page Links

Create internal links to other pages using double square brackets:

1

[[Page Name]]

This creates a clickable link to the specified page. If the page doesn’t exist, it will be created when clicked.

Kanban Board

Mon, 01 Jan 0001 00:00:00 +0000

The Kanban Board extension provides visual task management with customizable boards, filters, and drag-and-drop functionality. It’s perfect for organizing tasks across different projects, priorities, or workflows.

Features

Visual Task Management - Drag-and-drop interface for moving tasks between states
Multiple Boards - Configure different boards for different contexts (work, personal, projects)
Smart Filters - Show only tasks matching specific criteria
Real-time Updates - Changes sync immediately with your notes
Property Integration - Works seamlessly with notd’s property system

Board Configuration

The Kanban extension is configured through /extensions/kanban_board/config.json:

Ping

Mon, 01 Jan 0001 00:00:00 +0000

A simple utility endpoint to check if the API is running.

`GET /api/v1/ping.php`

Description: Checks API health.

Response (200 OK):

1
2
3
4


{
 "status": "pong",
 "timestamp": "2023-10-27T10:30:00+00:00"
}

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Pages

Pages are top-level containers for notes. Each page has a unique name and can contain multiple notes.

Notes

Notes are the core content blocks that belong to pages. Notes can be nested under other notes, creating a hierarchical structure.

Properties

Properties are metadata extracted from content using pattern matching:

{key::value} - Public property (weight 2)
{key:::value} - Internal property (weight 3)
{key::::value} - System log property (weight 4)

Task States

The API supports task status tracking with these states:

Excalidraw Editor

Mon, 01 Jan 0001 00:00:00 +0000

The Excalidraw Editor extension integrates the powerful Excalidraw visual whiteboard directly into notd, enabling you to create hand-drawn diagrams, sketches, and visual notes that are automatically saved as note attachments.

Features

Visual Drawing - Full-featured drawing canvas with shapes, text, and freehand drawing
Seamless Integration - Launch directly from note context menus
Automatic Saving - Drawings are saved as PNG attachments to specific notes
Offline Support - Works completely offline with phpdesktop
Modern Interface - React-based Excalidraw component with Alpine.js controls

Getting Started

Opening the Editor

From Note Context Menu - Right-click any note and select “Open in Excalidraw”
Direct Access - Navigate to the extension through the extensions menu
URL Parameters - Access with specific note ID: excalidraw.html?note_id=123

Creating Drawings

The Excalidraw editor provides:

Extensions

Mon, 01 Jan 0001 00:00:00 +0000

Retrieves details about currently active extensions.

`GET /api/v1/extensions.php`

Description: Lists active extensions defined in the configuration.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "status": "success",
 "data": {
 "extensions": [
 {
 "name": "calendar",
 "featherIcon": "calendar"
 },
 {
 "name": "tasks",
 "featherIcon": "check-square"
 }
 ]
 }
}

Journal & Tasks

Mon, 01 Jan 0001 00:00:00 +0000

Journal-Based Workflow

notd is built around a journal-based system inspired by tools like LogSeq. This approach uses date-based pages as the foundation for daily note-taking and organization.

Daily Journal Pages

By default, notd redirects to today’s date page (e.g., 2024-07-18). These journal pages:

Are automatically created when first accessed
Provide a consistent starting point for daily work
Can contain any type of content: notes, tasks, links, etc.
Form a chronological record of your thoughts and activities

Navigate between dates using:

Additional Extensions

Mon, 01 Jan 0001 00:00:00 +0000

notd includes several additional extensions that enhance your workflow with specialized tools and integrations. Each extension is designed to work seamlessly with the core system while providing focused functionality.

Attachment Dashboard 📎

The Attachment Dashboard provides centralized file management for organizing and accessing all your note attachments.

Features

Centralized View - See all attachments across your entire knowledge base
File Type Filtering - Filter by images, documents, spreadsheets, etc.
Search Capabilities - Find attachments by filename or associated note content
Quick Preview - Preview supported file types without leaving the dashboard
Bulk Operations - Manage multiple files at once

Usage Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Project Assets {category::project}

## Design Files
- Logo variations uploaded to dashboard
- Brand guidelines document attached
- Color palette reference images

## Documentation 
- Technical specifications PDF
- User manual drafts
- Meeting recordings

{attachments::managed}
{project::alpha}

Access the dashboard to:

Attachments

Mon, 01 Jan 0001 00:00:00 +0000

Manages file attachments for notes.

`POST /api/v1/attachments.php` (Upload)

Description: Uploads a new attachment for a note.
Request: multipart/form-data
- note_id (form field): 42
- attachmentFile (file field): (binary data of my-document.pdf)

Response (201 Created):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "status": "success",
 "data": {
 "id": 101,
 "note_id": 42,
 "name": "my-document.pdf",
 "path": "2023/10/uniqueid_my-document.pdf",
 "type": "application/pdf",
 "size": 123456,
 "created_at": "2023-10-27 10:30:00"
 }
}

`POST /api/v1/attachments.php` (Delete)

Description: Deletes an existing attachment.

Request: application/json

1
2
3
4


{
 "_method": "DELETE",
 "id": 101
}

Response (200 OK):

1
2
3
4
5
6


{
 "status": "success",
 "data": {
 "deleted_attachment_id": 101
 }
}

`GET /api/v1/attachments.php`

Description: Retrieves a list of attachments, either for a specific note or for all notes with pagination and filtering.
Example (By Note ID): GET /api/v1/attachments.php?note_id=42

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "status": "success",
 "data": [
 {
 "id": 101,
 "name": "my-document.pdf",
 "path": "2023/10/uniqueid_my-document.pdf",
 "type": "application/pdf",
 "size": 123456,
 "created_at": "2023-10-27 10:30:00",
 "url": "http://localhost/uploads/2023/10/uniqueid_my-document.pdf"
 }
 ]
}

Backlinks & Favorites

Mon, 01 Jan 0001 00:00:00 +0000

Backlinks System

Backlinks show you which pages reference the current page, helping you discover connections and relationships in your knowledge base.

How Backlinks Work

When you create a page link using [[Page Name]], notd automatically:

Creates a clickable link to that page
Adds the current page to the target page’s backlinks
Tracks these relationships in the Properties table

Viewing Backlinks

Backlinks appear in several places:

Sidebar - Shows recent backlinks to the current page
Backlinks Modal - Full list accessible via the backlinks button
Context - Shows which note on the source page contains the link

Backlinks Examples

If your “Project Alpha” page contains:

Quick Start Examples

Mon, 01 Jan 0001 00:00:00 +0000

1. Create a Page and Add Notes

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# Create a page with notes
curl -X POST http://localhost/api/v1/append_to_page \
 -H "Content-Type: application/json" \
 -d '{
 "page_name": "My Project",
 "notes": [
 {
 "content": "Project overview {priority::high}",
 "order_index": 1
 },
 {
 "content": "TODO Research competitors",
 "order_index": 2
 }
 ]
 }'

2. Search for Tasks

1
2


# Find all TODO tasks
curl "http://localhost/api/v1/search?tasks=TODO&page=1&per_page=10"

3. Get Recent Pages

1
2


# Get the 7 most recently updated pages
curl "http://localhost/api/v1/recent_pages"

4. Full-text Search

1
2


# Search for notes containing "project"
curl "http://localhost/api/v1/search?q=project&page=1&per_page=10"

5. Batch Operations

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# Create multiple notes in one request
curl -X POST http://localhost/api/v1/notes \
 -H "Content-Type: application/json" \
 -d '{
 "action": "batch",
 "operations": [
 {
 "type": "create",
 "payload": {
 "page_id": 1,
 "content": "First note {tags::important}",
 "order_index": 1
 }
 },
 {
 "type": "create",
 "payload": {
 "page_id": 1,
 "content": "Second note",
 "order_index": 2
 }
 }
 ]
 }'

Advanced Features

Mon, 01 Jan 0001 00:00:00 +0000

notd includes several advanced features that leverage both the backend API and frontend capabilities to create powerful workflows and automation.

Frontend-Driven Features

Dynamic SQL Queries

The frontend can execute SQL queries embedded directly in notes, providing powerful data analysis and reporting capabilities:

1

SQL{SELECT id FROM Notes WHERE content LIKE '%important%'}

This creates dynamic content that updates automatically when underlying data changes.

Query Examples

Project Dashboard:

Notes

Mon, 01 Jan 0001 00:00:00 +0000

Manages notes and their content. All property modifications are now done by updating the note’s content field.

`POST /api/v1/notes.php` (Batch Operations)

Description: Create, update, and delete multiple notes in a single atomic request. This is the primary method for all write operations on notes.

Request: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


{
 "action": "batch",
 "include_parent_properties": true, // Optional, boolean, defaults to false. If true, created/updated notes will include 'parent_properties'.
 "operations": [
 {
 "type": "create",
 "payload": {
 "client_temp_id": "temp-note-1",
 "page_id": 1,
 "parent_note_id": null, // or ID of parent note
 "content": "This is a new task.\n{status::TODO}\n{priority::High}"
 }
 },
 {
 "type": "update",
 "payload": {
 "id": 42, // ID of the note to update
 "content": "This is an updated task.\n{status::::DONE}\n{priority::High}"
 }
 },
 {
 "type": "delete",
 "payload": {
 "id": 56 // ID of the note to delete
 }
 }
 ]
}

Parameters:
- include_parent_properties (optional, boolean): When true, each note object returned in the results for create and update operations will include a parent_properties field. This field contains an aggregated view of properties from all direct and indirect parent notes. Defaults to false.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


{
 "status": "success",
 "data": {
 "message": "Batch operations completed. Check individual results for status.",
 "results": [
 {
 "type": "create",
 "status": "success",
 "note": {
 "id": 101,
 "content": "This is a new task...",
 "properties": {"status": [{"value": "TODO"}], "priority": [{"value": "High"}]},
 "parent_properties": {"project_code": [{"value": "Alpha"}]}, // Example if parent had {project_code::Alpha}
 "...": "..."
 },
 "client_temp_id": "temp-note-1"
 },
 {
 "type": "update",
 "status": "success",
 "note": {
 "id": 42,
 "content": "This is an updated task...",
 "properties": {"status": [{"value": "DONE"}], "priority": [{"value": "High"}]},
 "parent_properties": null, // Or {} if no parent properties, or if include_parent_properties was false
 "...": "..."
 }
 },
 {
 "type": "delete",
 "status": "success",
 "deleted_note_id": 56
 }
 ]
 }
}

Note on parent_properties in response:

The parent_properties field in the note object (for create and update results) will contain an object where keys are property names and values are arrays of property values inherited from parent notes. This structure mirrors the properties field.
It will be null or an empty object ({}) if include_parent_properties is false, if the note has no parent, or if no inheritable properties exist on its parents.

`GET /api/v1/notes.php?id={id}`

Description: Retrieves a single note, including its properties derived from its content.
- Accepts an optional boolean GET parameter include_internal (defaults to false). If true, internal properties (weight >= 3) are included. Otherwise, they are excluded.
- Accepts an optional boolean GET parameter include_parent_properties (defaults to false). If true, the parent_properties field will be populated.

Response (200 OK) - Example when include_internal=true and include_parent_properties=true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


{
 "status": "success",
 "data": {
 "id": 42,
 "page_id": 10,
 "content": "This is an updated task.\n{status::::DONE}\n{priority::High}\n{internal_marker:::secret info}",
 "parent_note_id": 20, // Assuming parent note 20 exists
 "order_index": 0,
 "collapsed": 0,
 "created_at": "2023-10-27 10:30:00",
 "updated_at": "2023-10-27 10:32:00",
 "properties": {
 "status": [
 { "value": "TODO", "weight": 2, "created_at": "2023-10-27 10:30:00" },
 { "value": "DONE", "weight": 4, "created_at": "2023-10-27 10:31:00" }
 ],
 "priority": [
 { "value": "High", "weight": 2, "created_at": "2023-10-27 10:30:00" }
 ],
 "internal_marker": [
 { "value": "secret info", "weight": 3, "created_at": "2023-10-27 10:32:00"}
 ]
 },
 "parent_properties": { // Example, assuming parent note 20 has {project_code::Alpha}
 "project_code": [{"value": "Alpha", "weight": 2, "created_at": "..."}]
 }
 }
}

If GET /api/v1/notes.php?id=42 (i.e., include_internal=false and include_parent_properties=false by default) is called, internal_marker from properties and the entire parent_properties field would be excluded:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// Response (200 OK) - Example when include_internal=false (default)
{
 "status": "success",
 "data": {
 "id": 42,
 "page_id": 10,
 "content": "This is an updated task.\n{status::::DONE}\n{priority::High}\n{internal_marker:::secret info}",
 "parent_note_id": null,
 "order_index": 0,
 "collapsed": 0,
 "created_at": "2023-10-27 10:30:00",
 "updated_at": "2023-10-27 10:32:00",
 "properties": {
 "status": [
 { "value": "TODO", "weight": 2, "created_at": "2023-10-27 10:30:00" }
 ],
 "priority": [
 { "value": "High", "weight": 2, "created_at": "2023-10-27 10:30:00" }
 ]
 }
 }
}

`GET /api/v1/notes.php?page_id={id}`

Description: Retrieves all notes for a specific page. Properties for each note are derived from its content. Accepts an optional boolean GET parameter include_internal (defaults to false). If true, internal properties (weight >= 3) for each note are included. Otherwise, they are excluded.

Example response for GET /api/v1/notes.php?page_id=10&include_internal=true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


{
 "status": "success",
 "data": [
 {
 "id": 42,
 "page_id": 10,
 "content": "First note with {secret:::shhh} and {public::data}",
 "parent_note_id": null,
 "order_index": 0,
 "collapsed": 0,
 "created_at": "2023-10-28 11:00:00",
 "updated_at": "2023-10-28 11:05:00",
 "properties": {
 "secret": [{"value": "shhh", "weight": 3, "created_at": "2023-10-28 11:05:00"}],
 "public": [{"value": "data", "weight": 2, "created_at": "2023-10-28 11:05:00"}]
 }
 },
 {
 "id": 43,
 "page_id": 10,
 "content": "Second note with {visible::info}",
 "parent_note_id": null,
 "order_index": 1,
 "collapsed": 0,
 "created_at": "2023-10-28 11:10:00",
 "updated_at": "2023-10-28 11:10:00",
 "properties": {
 "visible": [{"value": "info", "weight": 2, "created_at": "2023-10-28 11:10:00"}]
 }
 }
 ]
}

If GET /api/v1/notes.php?page_id=10 or GET /api/v1/notes.php?page_id=10&include_internal=false is called, the properties for note 42 would only include public.

Search & Navigation

Mon, 01 Jan 0001 00:00:00 +0000

notd provides powerful search capabilities that help you find information quickly across all your notes, pages, and attachments. The search system integrates with all frontend features including encryption, properties, and backlinks.

Global Search

Search Interface

The global search is accessible from the sidebar and provides:

Real-time results - Search as you type with debounced queries
Content highlighting - Search terms are highlighted in results
Context snippets - Preview content around matching terms
Property filtering - Filter by page and note properties
Mixed results - Pages and notes shown together with clear distinction

Search Syntax

Basic Search

project management

Finds content containing both “project” and “management”.

Best Practices

Mon, 01 Jan 0001 00:00:00 +0000

1. Use Batch Operations

For multiple note operations, use batch operations instead of individual requests:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


// Good
const batchResponse = await fetch('/api/v1/notes', {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({
 action: 'batch',
 operations: [
 { type: 'create', payload: {...} },
 { type: 'update', payload: {...} }
 ]
 })
});

// Avoid
await fetch('/api/v1/notes', { method: 'POST', body: JSON.stringify({...}) });
await fetch('/api/v1/notes', { method: 'POST', body: JSON.stringify({...}) });

2. Include Parent Properties

When fetching notes, consider including parent properties for context:

Pages

Mon, 01 Jan 0001 00:00:00 +0000

Manages pages, which now also have a content field to drive their properties.

`POST /api/v1/pages.php` (Create)

Description: Creates a new page.

Request: application/json

1
2
3
4


{
 "name": "New Project Page",
 "content": "{type::Project}\n{lead:::John Doe}"
}

Response (201 Created):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "status": "success",
 "data": {
 "id": 25,
 "name": "New Project Page",
 "content": "{type::Project}\n{lead:::John Doe}",
 "created_at": "2023-10-27 10:35:00",
 "updated_at": "2023-10-27 10:35:00",
 "properties": {
 "type": [{"value": "Project", "weight": 2, "created_at": "2023-10-27 10:35:00"}],
 "lead": [{"value": "John Doe", "weight": 3, "created_at": "2023-10-27 10:35:00"}]
 }
 }
}

`POST /api/v1/pages.php` (Update)

Description: Updates a page’s name or content.

Request: application/json

1
2
3
4
5


{
 "_method": "PUT",
 "id": 25,
 "content": "{type::Project}\n{lead:::Jane Doe}\n{status::Active}"
}

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "status": "success",
 "data": {
 "id": 25,
 "name": "New Project Page",
 "content": "{type::Project}\n{lead:::Jane Doe}\n{status::Active}",
 "...": "...",
 "properties": { "..." : "..." }
 }
}

`POST /api/v1/pages.php` (Delete)

Description: Deletes a page and all its associated notes.

Request: application/json

1
2
3
4


{
 "_method": "DELETE",
 "id": 25
}

Response (200 OK):

1
2
3
4
5
6


{
 "status": "success",
 "data": {
 "deleted_page_id": 25
 }
}

`GET /api/v1/pages.php?name={page_name}`

Description: Retrieves a page by its exact name. If the page does not exist, it will be created with null content.
Request example: GET /api/v1/pages.php?name=My%20New%20Page

Response example for an existing page (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "status": "success",
 "data": {
 "id": 26,
 "name": "My New Page",
 "content": "Some existing content.",
 "created_at": "2023-10-28 10:00:00",
 "updated_at": "2023-10-28 10:05:00",
 "properties": {}
 }
}

Response example for a newly created page (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "status": "success",
 "data": {
 "id": 27,
 "name": "My New Page",
 "content": null,
 "created_at": "2023-10-28 10:10:00",
 "updated_at": "2023-10-28 10:10:00",
 "properties": {}
 }
}

`GET /api/v1/pages.php?id={id}`

Description: Retrieves a single page by its ID.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "status": "success",
 "data": {
 "id": 25,
 "name": "New Project Page",
 "content": "{type::Project}\n{lead:::Jane Doe}\n{status::Active}",
 "created_at": "2023-10-27 10:35:00",
 "updated_at": "2023-10-27 10:40:00",
 "properties": {
 "type": [{"value": "Project", "weight": 2, "created_at": "2023-10-27 10:35:00"}],
 "lead": [{"value": "Jane Doe", "weight": 3, "created_at": "2023-10-27 10:40:00"}],
 "status": [{"value": "Active", "weight": 2, "created_at": "2023-10-27 10:40:00"}]
 }
 }
}

`GET /api/v1/pages.php?date={YYYY-MM-DD}`

Description: Retrieves a list of pages that have a property ‘date’ matching the specified date. The date must be in YYYY-MM-DD format.
Request example: GET /api/v1/pages.php?date=2023-11-15

Response example (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{
 "status": "success",
 "data": [
 {
 "id": 30,
 "name": "Meeting Notes 2023-11-15",
 "content": "Discussed project milestones.\n{date::2023-11-15}",
 "alias": null,
 "updated_at": "2023-11-15 14:00:00"
 },
 {
 "id": 31,
 "name": "Daily Log 2023-11-15",
 "content": "Logged daily activities.\n{date::2023-11-15}",
 "alias": "today-log",
 "updated_at": "2023-11-15 16:30:00"
 }
 ]
}

If no pages match the date, an empty array will be returned in the data field.
1 2 3 4

{ "status": "success", "data": [] }

`GET /api/v1/pages.php` (List)

Description: Retrieves a paginated list of pages.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "status": "success",
 "data": [
 {
 "id": 25,
 "name": "New Project Page",
 "content": "...",
 "properties": { "...": "..." }
 }
 ],
 "pagination": { "total_items": 1, "...": "..." }
}

User Interface

Mon, 01 Jan 0001 00:00:00 +0000

notd features a modern, responsive user interface built with Alpine.js and designed for efficient note-taking and knowledge management. This guide covers the interface components, interactions, and customization options.

Interface Overview

Main Layout

The notd interface consists of several key areas:

Sidebar - Navigation, search, recent pages, favorites, and calendar
Main Content Area - Note editing and viewing
Toolbar - Action buttons and extension access
Status Bar - Page information and connection status

Responsive Design

notd adapts to different screen sizes:

Append to Page

Mon, 01 Jan 0001 00:00:00 +0000

A utility endpoint to quickly add notes to a page, creating the page if it doesn’t exist.

`POST /api/v1/append_to_page.php`

Description: Appends one or more notes to a page, creating the page if necessary. Supports creating nested notes in one call.

Request: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "page_name": "Meeting Notes 2023-10-27",
 "notes": [
 {
 "client_temp_id": "topic-1",
 "content": "Discussion Topic 1: Budget {priority::High}",
 "order_index": 0
 },
 {
 "content": "Action Item: Follow up with finance. {status::TODO}",
 "parent_note_id": "topic-1",
 "order_index": 0
 }
 ]
}

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


{
 "status": "success",
 "data": {
 "message": "Page created and notes appended successfully.",
 "page": {
 "id": 27,
 "name": "Meeting Notes 2023-10-27",
 "content": null,
 "properties": {},
 "...": "..."
 },
 "appended_notes": [
 {
 "id": 103,
 "page_id": 27,
 "content": "Discussion Topic 1: Budget {priority::High}",
 "properties": { "priority": [{"value": "High", "weight": 2, "...":"..."}] },
 "...": "..."
 },
 {
 "id": 104,
 "page_id": 27,
 "parent_note_id": 103,
 "content": "Action Item: Follow up with finance. {status::TODO}",
 "properties": { "status": [{"value": "TODO", "weight": 2, "...":"..."}] },
 "...": "..."
 }
 ]
 }
}

Best Practices

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers best practices for using notd effectively, drawn from real-world usage patterns and team collaboration experiences.

Content Organization

Naming Conventions

Use consistent, descriptive page names:

1
2
3
4
5
6
7
8
9


# Good Examples
Meeting Notes - Project Alpha - 2024-07-18
Project Alpha/Requirements
Team/John Smith/Performance Review 2024

# Avoid
mtg notes
proj requirements 
john stuff

Establish team conventions:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Common Issues

Database Locked Errors
- The API will retry automatically
- If persistent, check for long-running transactions
Property Not Found
- Properties are extracted from content automatically
- Check that your content uses the correct syntax: {key::value}
Search Not Working
- Ensure search terms are properly URL-encoded
- Check that the content contains the search terms
Template Processing Errors
- Verify template syntax
- Check that placeholder names are valid

Debug Mode

Enable debug logging by checking the server logs for detailed error information.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Version 1.0.0

Initial API release
Full CRUD operations for pages and notes
Property system with pattern matching
Full-text search capabilities
File attachment support
Template system
Webhook notifications
Batch operations for efficiency

Properties

Mon, 01 Jan 0001 00:00:00 +0000

This endpoint is now read-only. It provides a way to query the Properties table index directly, which can be useful for advanced filtering or finding all entities with a specific property value, without needing to perform a full-text search.

`GET /api/v1/properties.php`

Description: Retrieves all indexed properties for a specific entity.
Example Call: GET /api/v1/properties.php?entity_type=note&entity_id=42

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "status": "success",
 "data": {
 "status": [
 { "id": 201, "value": "TODO", "weight": 2, "created_at": "2023-10-27 10:30:00" },
 { "id": 205, "value": "DONE", "weight": 4, "created_at": "2023-10-27 10:31:00" }
 ],
 "priority": [
 { "id": 202, "value": "High", "weight": 2, "created_at": "2023-10-27 10:30:00" }
 ]
 }
}

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Common issues and solutions for notd frontend features.

Search Issues

Search Not Finding Content

Problem: Global search returns no results for content you know exists.

Solutions:

Check encryption status - Encrypted content requires the page password
Verify content is saved - Ensure changes were saved before searching
Check property syntax - Properties must use correct syntax: {key::value}
Search different terms - Try broader or alternative keywords

Example Fix:

1
2
3


# If searching for: "project planning"
# Try instead: "project" or "planning" separately
# Or check if content uses different terms like "project preparation"

Search Results Missing Context

Problem: Search results don’t show enough context around matching terms.

Search

Mon, 01 Jan 0001 00:00:00 +0000

Provides powerful search capabilities. It can search by term, find backlinks, list tasks, or list favorited pages.

General Parameters for search types returning notes (e.g., q, backlinks_for_page_name, tasks):

include_parent_properties (optional, boolean): Defaults to false. If set to true, each note item in the results array will include a parent_properties field. This field contains an object with aggregated properties from all direct and indirect parent notes. The structure mirrors the main properties field. For search types that do not return notes (e.g., favorites), this parameter has no effect.

`GET /api/v1/search.php?q={term}`

Description: Performs a full-text search across note content. Also supports pagination parameters (page, per_page).
Example URL: /api/v1/search.php?q=meeting&include_parent_properties=true

Response (200 OK) when include_parent_properties=true:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


{
 "status": "success",
 "data": {
 "results": [
 {
 "note_id": 42,
 "content": "The full content of the note mentioning the search term.",
 "page_id": 10,
 "page_name": "Project Alpha",
 "content_snippet": "... with the search <mark>term</mark> highlighted ...",
 "properties": { "status": [{"value": "TODO"}] },
 "parent_properties": { "project_code": [{"value": "Alpha"}] }
 }
 ],
 "pagination": { "total_items": 1, "current_page": 1, "per_page": 20, "total_pages": 1 }
 }
}

If include_parent_properties is false (default), the parent_properties field will be an empty object ({}) or null.

The Search endpoint also supports other modes:

Query Notes

Mon, 01 Jan 0001 00:00:00 +0000

Executes safe, predefined SQL queries against the indexed Properties table to find notes. This becomes even more powerful for historical queries.

`POST /api/v1/query_notes.php`

Description: Fetches notes that match a specific, secure SQL query pattern.

Request: application/json

1
2
3
4
5


{
 "sql_query": "SELECT N.id FROM Notes N JOIN Properties P ON N.id = P.note_id WHERE P.name = 'status' AND P.value = 'DONE' AND P.created_at > '2023-10-27'",
 "page": 1,
 "per_page": 10
}

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "status": "success",
 "data": [
 {
 "id": 42,
 "content": "This is an updated task.\n{status::::DONE}\n{priority::High}",
 "properties": { "...": "..." },
 "...": "..."
 }
 ],
 "pagination": { "current_page": 1, "...": "..." }
}

Templates

Mon, 01 Jan 0001 00:00:00 +0000

Manages reusable templates for creating notes and pages.

`POST /api/v1/templates.php` (Create)

Description: Creates a new template.

Request: application/json

1
2
3
4
5
6


{
 "_method": "POST",
 "type": "note",
 "name": "daily-review",
 "content": "## Daily Review\n\n### What went well?\n\n- \n\n### What could be improved?\n\n- "
}

Response (201 Created):

1
2
3
4
5
6


{
 "status": "success",
 "data": {
 "message": "Template created successfully"
 }
}

`GET /api/v1/templates.php?type=note`

Description: Retrieves all available templates of a given type.

Response (200 OK):

1
2
3
4
5
6
7
8
9


{
 "status": "success",
 "data": [
 {
 "name": "daily-review",
 "content": "## Daily Review\n\n### What went well?\n\n- \n\n### What could be improved?\n\n- "
 }
 ]
}

Webhooks

Mon, 01 Jan 0001 00:00:00 +0000

Manages webhook subscriptions for event notifications.

`POST /api/v1/webhooks.php` (Create)

Description: Registers a new webhook.

Request: application/json

1
2
3
4
5
6


{
 "url": "https://example.com/webhook-receiver",
 "entity_type": "note",
 "property_names": ["status", "priority"],
 "event_types": ["property_change", "entity_created"]
}

Response (201 Created):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "status": "success",
 "data": {
 "id": 1,
 "url": "https://example.com/webhook-receiver",
 "entity_type": "note",
 "property_names": ["status", "priority"],
 "event_types": ["property_change", "entity_created"],
 "secret": "whsec_... (only shown on creation)",
 "...": "..."
 }
}

`POST /api/v1/webhooks.php?action=test&id=1`

Description: Sends a test event to the specified webhook.

Response (200 OK):

1
2
3
4
5
6


{
 "status": "success",
 "data": {
 "message": "Test event sent. Check history for result."
 }
}

`GET /api/v1/webhooks.php?action=history&id=1`

Description: Retrieves the delivery history for a webhook.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{
 "status": "success",
 "data": {
 "pagination": { "total": 1, "page": 1, "limit": 20 },
 "history": [
 {
 "id": 1,
 "webhook_id": 1,
 "event_type": "test",
 "payload": "{\"event\":\"test\",...}",
 "response_code": 200,
 "response_body": "{\"status\":\"ok\"}",
 "success": 1,
 "created_at": "2023-10-27 11:00:00"
 }
 ]
 }
}

`GET /api/v1/webhooks.php` (List)

Description: Lists all configured webhooks.

Response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "status": "success",
 "data": [
 {
 "id": 1,
 "url": "https://example.com/webhook-receiver",
 "entity_type": "note",
 "property_names": ["status", "priority"],
 "event_types": ["property_change", "entity_created"],
 "active": 1,
 "verified": 1,
 "last_triggered": "2023-10-27 11:00:00"
 }
 ]
}

Company

Mon, 01 Jan 0001 00:00:00 +0000

notd: a simple outliner on notd

Frontend Quick Start

First Steps

1. Understanding the Interface

2. Create Your First Note

Core Features

Rich Text Editing with Markdown

Page Links

Kanban Board

Features

Board Configuration

Ping

GET /api/v1/ping.php

Core Concepts

Pages

Notes

Properties

Task States

Excalidraw Editor

Features

Getting Started

Opening the Editor

Creating Drawings

Extensions

GET /api/v1/extensions.php

Journal & Tasks

Journal-Based Workflow

Daily Journal Pages

Date Navigation

Additional Extensions

Attachment Dashboard 📎

Features

Usage Examples

Attachments

POST /api/v1/attachments.php (Upload)

POST /api/v1/attachments.php (Delete)

GET /api/v1/attachments.php

Backlinks & Favorites

Backlinks System

How Backlinks Work

Viewing Backlinks

Backlinks Examples

Quick Start Examples

1. Create a Page and Add Notes

2. Search for Tasks

3. Get Recent Pages

4. Full-text Search

5. Batch Operations

Advanced Features

Frontend-Driven Features

Dynamic SQL Queries

Query Examples

Notes

POST /api/v1/notes.php (Batch Operations)

GET /api/v1/notes.php?id={id}

GET /api/v1/notes.php?page_id={id}

Search & Navigation

Global Search

Search Interface

Search Syntax

Basic Search

Best Practices

1. Use Batch Operations

2. Include Parent Properties

Pages

POST /api/v1/pages.php (Create)

POST /api/v1/pages.php (Update)

POST /api/v1/pages.php (Delete)

GET /api/v1/pages.php?name={page_name}

GET /api/v1/pages.php?id={id}

GET /api/v1/pages.php?date={YYYY-MM-DD}

GET /api/v1/pages.php (List)

User Interface

Interface Overview

Main Layout

Responsive Design

Append to Page

POST /api/v1/append_to_page.php

Best Practices

Content Organization

`GET /api/v1/ping.php`

`GET /api/v1/extensions.php`

`POST /api/v1/attachments.php` (Upload)

`POST /api/v1/attachments.php` (Delete)

`GET /api/v1/attachments.php`

`POST /api/v1/notes.php` (Batch Operations)

`GET /api/v1/notes.php?id={id}`

`GET /api/v1/notes.php?page_id={id}`

`POST /api/v1/pages.php` (Create)

`POST /api/v1/pages.php` (Update)

`POST /api/v1/pages.php` (Delete)

`GET /api/v1/pages.php?name={page_name}`

`GET /api/v1/pages.php?id={id}`

`GET /api/v1/pages.php?date={YYYY-MM-DD}`

`GET /api/v1/pages.php` (List)

`POST /api/v1/append_to_page.php`

`GET /api/v1/properties.php`

`GET /api/v1/search.php?q={term}`

`POST /api/v1/query_notes.php`

`POST /api/v1/templates.php` (Create)

`GET /api/v1/templates.php?type=note`

`POST /api/v1/webhooks.php` (Create)

`POST /api/v1/webhooks.php?action=test&id=1`

`GET /api/v1/webhooks.php?action=history&id=1`

`GET /api/v1/webhooks.php` (List)