mathieu/personotes
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96f895b2549f13748f32cb6cf639ae67fc51ea9a
personotes/GEMINI.md

5.7 KiB
Raw Blame History

Project Notes

A lightweight, web-based Markdown note-taking application with a Go backend and a minimalist frontend built with htmx. It allows users to create, edit, delete, and search Markdown notes, with automatic front matter management and a live Markdown preview.

Features

  • File-based Notes: All notes are stored as plain Markdown files (.md) on the filesystem.
  • Tag Indexing: Notes are indexed by tags specified in their YAML front matter, enabling quick search.
  • Live Markdown Preview: A side-by-side editor and live preview pane for a better writing experience.
  • Automatic Front Matter: Automatically generates and updates title, date (creation), last_modified, and tags in YAML front matter.
  • Slash Commands: Insert common Markdown elements and dynamic content (like current date) using / commands in the editor.
  • Dynamic File Tree: An automatically updating file tree in the sidebar to navigate notes.
  • Lightweight Frontend: Built with htmx for dynamic interactions, minimizing JavaScript complexity.
  • Hierarchical Organization: Organize notes in folders with drag-and-drop file management.
  • Rich Search: Search by keywords, tags (tag:projet), title (title:meeting), or path (path:backend).
  • Go Backend: A fast and efficient Go server handles file operations, indexing, and serving the frontend.

Technologies Used

  • Backend: Go
    • net/http: Standard library for the web server.
    • github.com/fsnotify/fsnotify: For watching file system changes and re-indexing.
    • gopkg.in/yaml.v3: For parsing and marshaling YAML front matter.
  • Frontend: HTML, CSS, JavaScript
    • htmx: For dynamic UI interactions without writing much JavaScript.
    • marked.js: For client-side Markdown parsing in the preview.
    • DOMPurify: For sanitizing HTML output from Markdown to prevent XSS vulnerabilities.
    • Highlight.js: For syntax highlighting in code blocks.
    • Custom CSS theme with dark mode inspired by VS Code and GitHub Dark.

Frontend Build Process

The frontend assets (JavaScript, CSS) are built and optimized using Vite. When changes are made to the frontend source code (e.g., in frontend/src/), the npm run build command must be executed from the frontend/ directory. This command compiles, bundles, and minifies the source files into static assets (located in static/dist/) that the Go backend serves to the browser. This step is crucial to ensure that the latest frontend changes are reflected in the application.

Getting Started

Prerequisites

  • Go (version 1.22 or higher recommended)

Installation

  1. Clone the repository: 
    git clone https://github.com/mathieu/project-notes.git
cd project-notes
  2. Download Go modules: 
    go mod tidy

Running the Application

To start the Go backend server:

go run ./cmd/server

The application will be accessible in your web browser at http://localhost:8080.

Usage

Creating a New Note

  1. Click the "✨ Nouvelle note" button in the header.
  2. Enter a filename (e.g., my-new-note.md) in the modal dialog.
  3. Click "Créer / Ouvrir" - if the note exists, it will be opened; otherwise, a new note will be created.
  4. An editor will appear with pre-filled YAML front matter (title, creation date, last modified date, and a "default" tag).

Editing a Note

  1. Click on a note in the "Notes" file tree in the sidebar.
  2. The note's content will load into the editor.
  3. Make your changes in the left pane (textarea). The right pane will show a live preview.
  4. Click the "Enregistrer" button or use Ctrl/Cmd+S to save your changes. The last_modified date in the front matter will be updated automatically.

Searching Notes

The search supports multiple query formats:

  1. General search: Type keywords to search across title, tags, path, and content.
  2. Tag filter: Use tag:projet to filter by specific tags.
  3. Title filter: Use title:meeting to search within note titles.
  4. Path filter: Use path:backend to search by file path.
  5. Quoted phrases: Use "exact phrase" to search for exact matches.

Results are scored and ranked by relevance (title matches score highest).

Using Slash Commands

  1. While editing a note, type / at the start of a line in the textarea.
  2. A command palette will appear with available commands.
  3. Type to filter commands (e.g., /h1, /date, /table).
  4. Use ArrowUp/ArrowDown to navigate and Enter or Tab to select a command.
  5. The corresponding Markdown snippet will be inserted at your cursor position.

Available commands: h1, h2, h3, list, date, link, bold, italic, code, codeblock, quote, hr, table

Organizing Notes in Folders

  1. Click the "📁 Nouveau dossier" button in the sidebar.
  2. Enter a folder path (e.g., projets or projets/backend).
  3. The folder will be created and appear in the file tree.
  4. Drag and drop notes between folders to reorganize them.

Deleting a Note

  1. Load the note you wish to delete into the editor.
  2. Click the "Supprimer" button.
  3. Confirm the deletion when prompted. The note will be removed from the filesystem and the file tree will update automatically.

Server Configuration

The server accepts the following command-line flags:

  • -addr :PORT - Change server address (default: :8080)
  • -notes-dir PATH - Change notes directory (default: ./notes)

Example:

go run ./cmd/server -addr :3000 -notes-dir ~/my-notes