NoteDiscovery Documentation

When a note is shared via a public link, the following features and behaviors apply:

• Theme preservation: The shared view uses the theme that was active when the link was created.
• Content rendering: Images, MathJax equations, Mermaid diagrams, and code syntax highlighting are all rendered in the shared view.
• Code blocks: Include a copy-to-clipboard button for viewers.
• Persistence: Links do not expire automatically; they remain active until you manually revoke them.
• Read-only access: Viewers can see the content but cannot edit the note.
• Visual indicators: Shared notes are marked with a share icon in the sidebar.

NoteDiscovery loads configuration in a specific order. Later sources override earlier ones:

1. config.yaml: The base default configuration.
2. Environment Variables: Runtime overrides (useful for deployment-specific settings).
3. Command Line: The highest priority (if applicable).

To stop sharing a note and invalidate its public URL:

1. Open the note.
2. Click the Share button.
3. Click Revoke Link.

Once revoked, the previous URL will immediately stop working and access will be denied.

NoteDiscovery supports multiple interface languages via JSON locale files located in the locales/ directory. You can select a language by navigating to Settings (gear icon) → Language within the application UI.

To add your own language, create translation files following the project's contribution guidelines. If running via Docker, you can add or override translations by mounting a custom locales folder to /app/locales.

volumes:
  - ./locales:/app/locales  # Custom translations

NoteDiscovery is designed for self-hosted, private use. Follow these security practices:

Network Security

• Do NOT expose directly to the internet without additional security measures.
• Use a reverse proxy (e.g., nginx, Caddy) with HTTPS for production.
• Access the app via a local network or VPN.
• The app listens on 0.0.0.0:8000 by default.

Authentication

• Password protection is DISABLED by default (default password: admin).
• Action Required: Enable authentication and change the default password if exposing the app to a network.
• To disable authentication, set authentication.enabled: false in config.yaml.
• For multi-user setups, use a reverse proxy with OAuth/SSO.

Data Privacy

• Notes are stored as plain text markdown files in the data/ folder.
• No data is sent to external services.
• Perform regular backups of the data/ directory.

Highlight important information using GitHub-style callouts. These render as colored, bordered blocks in the preview pane. To use them, start a blockquote with > [!TYPE] on its own line.

Supported Types:

• [!NOTE] - General information (blue)
• [!TIP] - Helpful advice (green)
• [!IMPORTANT] - Crucial information (purple)
• [!WARNING] - Urgent caution (amber)
• [!CAUTION] - Negative consequences (red)

You can also add a custom title on the same line as the type: > [!TIP] Custom title.

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP] Custom title
> Helpful advice for doing things better or more easily.

You can use tags to navigate and narrow down your notes through several methods:

• Sidebar Filtering: Click any tag in the sidebar to filter notes. Selecting multiple tags applies AND logic (only notes containing all selected tags are displayed).
• Combined Search: You can combine text search with tag filters. For example, searching for the text "async" while having the tag "python" selected will only show notes containing "async" that are also tagged "python".

Display Modes:

Deploy a local AI stack consisting of NoteDiscovery (Markdown notes), Open WebUI (ChatGPT-style UI), and Ollama (Local LLM runtime) using Docker Compose.

Service URLs:

• NoteDiscovery: http://localhost:8000
• Open WebUI: http://localhost:3000
• Ollama: http://localhost:11434 (OpenAI-compatible at /v1)

Prerequisites:

• Docker Desktop (Windows/macOS) or Docker Engine + Compose v2 (Linux)
• ~5 GB free disk, ~2 GB free RAM

Steps:

1. From the repository root, run:

docker compose -f docker-compose.ollama-stack.yml up -d
docker compose -f docker-compose.ollama-stack.yml logs -f ollama-init

2. Wait until the logs show Model ready. (The first run pulls images and the default qwen2.5:1.5b model, which takes 5–10 minutes).
3. Access the apps at the URLs listed above. Notes are saved to the ./data/ directory.

NoteDiscovery is a simple single-user system. For secure deployments, follow these guidelines:

• Use HTTPS: Always run behind a reverse proxy like Traefik, nginx, or Caddy.
• Strong Passwords: Use at least 12 characters with mixed case, numbers, and symbols.
• Unique Secret Keys: Never reuse secret keys across different applications.
• Secure Configuration: Do not commit credentials or secret keys to version control.

Limitations: This system is NOT suitable for multi-user environments, public internet access without HTTPS, or strict compliance requirements (e.g., HIPAA, GDPR).

For MCP servers, scripts, or automation, you can use an API key instead of session cookies. API key authentication works simultaneously with session-based web UI authentication.

1. Generate a key

python -c "import secrets; print(secrets.token_hex(32))"

2. Configure the key

Via config.yaml:

authentication:
  api_key: "your_64_character_hex_key"

Via Environment Variable (Docker): Set AUTHENTICATION_API_KEY to your generated key.

3. Use the key in requests

You can authenticate using either a Bearer token or the X-API-Key header.

# Option 1: Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/api/notes

# Option 2: X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/api/notes

You can use your local Ollama instance as the chat model within Cursor. Note that this only affects the chat model picker; Cursor Tab and background jobs will continue to use Cursor's cloud models.

Configuration: In Cursor, navigate to Settings → Models → add a custom OpenAI-compatible model and use these settings:

• Base URL: http://localhost:11434/v1
• API Key: ollama (or any string)
• Model: qwen2.5:1.5b (or your preferred model)

Note: If Cursor rejects the local URL (common in older versions that validate URLs from the cloud), you must expose the local service via a tunnel (e.g., cloudflared tunnel --url http://localhost:11434) and use the resulting tunnel URL as the Base URL instead.