← Back to all projects
v1.0.0 PHP Web Application MySQL Notes Tools

SLD-Blocknotes

A modern, zero-dependency block-based notes and technical command management web application built with Pure PHP, Vanilla CSS, Vanilla JS, and MySQL/MariaDB. Features include collapsible notes, terminal command subnotes with 1-click clipboard copy, real-time live search, JSON export/import, 4-language localization, customizable user landing pages and HSL theme colors, and an automated first-start setup wizard.

Live Demo Download (.ZIP) (v1.0.0) Gitea Repository
SLD-Blocknotes Web Application Interface

Overview of the SLD-Blocknotes interface displaying notes, terminal command blocks, and real-time live search.

Key Features

SLD-Blocknotes is a modern, lightweight, and completely zero-dependency web application built for organizing structured technical notes, procedures, instructions, code snippets, and terminal commands. Engineered with Pure PHP, Vanilla CSS, Vanilla JavaScript, and MySQL/MariaDB, it provides maximum performance, minimal resource usage, and frictionless deployment on any Linux server or standard LAMP/LEMP stack.

  • Hierarchical Block Structure: Three-tier organization: Blocknotes → Notes → Subnotes.
  • Collapsible Notes (Accordion UI): Note blocks are collapsed by default to maximize vertical screen space and overview clarity. Features global "Expand All" and "Collapse All" action buttons.
  • Terminal Command Subnotes: Dedicated rendering for terminal commands in a high-contrast IDE/console code box with max-height vertical scrolling and a 1-Click Clipboard Copy button with immediate visual confirmation (✓ Copied!).
  • Real-Time Live Search: Instant client-side search bar filtering note titles, descriptions, subnote titles, and terminal command contents, automatically expanding matched note blocks.
  • JSON Storage Engine with Import & Export: Each blocknote is stored as an independent JSON file in blocknotes/. Download any blocknote with a single click for instant backups, or import existing JSON files with built-in backward compatibility for legacy formats.
  • Native 4-Language Localization (IT, EN, ES, FR): Complete interface translation in English 🇬🇧, Italian 🇮🇹, Spanish 🇪🇸, and French 🇫🇷 with a quick navbar dropdown switcher and persistent database preferences for each user profile.
  • Customizable User Landing Page: Users can configure their preferred landing page upon login—either jumping directly into the Global Dashboard or automatically opening a specific Default Blocknote.
  • Role-Based Access Control & Immune Owner: 3-tier user hierarchy (owner > admin > user). The primary Owner account cannot be deleted by any administrator or by themselves, nor demoted.
  • Site Customization (Owner Exclusive): The Owner can customize the global application site title and upload a high-resolution custom Favicon (with format validation and minimum 64x64px resolution verification).
  • Custom HSL Theme Colors: Every user can personalize the UI color scheme by adjusting Primary, Secondary, and Tertiary HSL hue angles.
  • Automated First Start Setup Wizard (first_start.php): Guided multilingual installer that detects the first run, creates the database schema and tables, provisions Owner and Admin credentials, and creates a secure installation lock.
  • Live Online Demo with Hourly Auto-Reset: Fully functioning demonstration instance publicly accessible online that auto-resets every hour for instant evaluation.

Live Demo & Test Environment

A public demonstration instance of SLD-Blocknotes is available online for testing all application features, creating notes, experimenting with the search engine, and evaluating the UI without setting up a local server:

Parameter Access Detail
Live Demo URL https://test-sld-blocknote.sld-server.org/
Administrator Username admin
Administrator Password admin123
Reset Frequency Automatic reset every hour (database and blocknote JSON files are fully wiped and restored to clean initial states)
Security & Privacy Notice Although the test environment is automatically reset and wiped every 60 minutes, it is strictly advised never to enter personal information, real passwords, private keys, or sensitive data inside test notes created on the public demo instance.

Project Structure

The application follows a clean, modular architecture with zero external package managers or vendor folders:

📁 sld-blocknotes/
├── 📂 assets/
│   ├── 📂 css/
│   │   ├── 📄 animations.css        # CSS keyframe animations and transitions
│   │   ├── 📄 style.css             # Main stylesheet, responsive layout & components
│   │   └── 📄 variables.css         # HSL color palette and design tokens
│   ├── 📂 js/
│   │   └── 📄 main.js               # Vanilla JS modals, collapsible notes, live search & clipboard copy
│   └── 📂 img/                      # Application icons, uploaded favicons and branding assets
├── 📂 blocknotes/                   # JSON storage directory for user blocknotes
│   └── 📄 .gitkeep
├── 📂 config/
│   ├── 📄 constants.php             # System path definitions and URL constants
│   ├── 📄 db.php                    # MySQL connection, schema auto-migration & installer router
│   ├── 📄 functions_init.php        # Routing controller and page parameter sanitizer
│   ├── 📄 init.php                  # Session initialization and helper loader
│   └── 📄 settings.php              # Auto-generated database credentials configuration
├── 📂 functions/
│   ├── 📄 auth.php                  # Authentication, password hashing & hierarchical RBAC
│   ├── 📄 blocknotes.php            # CRUD logic for blocknotes, notes, subnotes & JSON import
│   ├── 📄 functions.php             # Global helper function autoloader
│   ├── 📄 lang.php                  # Multilingual translation dictionary (EN, IT, ES, FR)
│   └── 📄 site_settings.php         # Site title manager and high-res favicon upload validator
├── 📂 includes/
│   ├── 📄 head_links.php            # HTML header CSS and metadata inclusions
│   └── 📄 js_footer.php             # Footer script tags and JS initialization
├── 📂 pages/
│   ├── 📄 404.php                   # Page not found error view
│   ├── 📄 about.php                 # Project information page
│   ├── 📄 admin_users.php           # User administration panel and Owner site settings
│   ├── 📄 db-error.php              # Database connection error display
│   ├── 📄 env-error.php             # Environment / PHP extension error display
│   ├── 📄 export_blocknote.php      # Blocknote JSON download endpoint
│   ├── 📄 home.php                  # Main dashboard listing all accessible blocknotes
│   ├── 📄 login.php                 # Multilingual user authentication page
│   ├── 📄 logout.php                # Session termination handler
│   ├── 📄 profile.php               # User profile, theme colors, language & landing page settings
│   └── 📄 view_blocknote.php        # Single blocknote detail view with collapsible notes & live search
├── 📂 templates/
│   ├── 📄 footer.php                # Global page footer template
│   └── 📄 header.php                # Navigation bar, user badge and language switcher
├── 📄 .gitignore
├── 📄 .htaccess                     # Apache URL rewrite and folder protection rules
├── 📄 first_start.php               # Automated First Start Installation Wizard
├── 📄 index.php                     # Central application router and entry point
└── 📄 LICENSE                       # MIT Open Source License

Module Responsibilities

Module / File Role & Responsibility
first_start.php Interactive installer wizard for initializing MySQL connection, database creation, table migrations, and setting up initial Owner & Admin accounts.
config/db.php Manages MySQL database connection using mysqli, runs automatic table migrations, and redirects to installer on first run.
functions/auth.php Handles secure user authentication with password_hash(), role enforcement (owner, admin, user), and Owner account immunity protections.
functions/blocknotes.php Full CRUD engine for reading, creating, updating, and deleting blocknotes, notes, and subnotes as JSON files on disk, plus JSON import parser.
functions/lang.php Internationalization engine supporting 4 languages (EN, IT, ES, FR) with automatic session tracking and the __('key') translation helper.
functions/site_settings.php Stores dynamic site configuration (e.g. site title) and provides secure favicon uploading with minimum dimension checks.
assets/js/main.js Client-side interactivity: responsive modals, collapsible note accordions, real-time live search filter, and 1-click clipboard copy.

System Requirements

  • Web Server: Apache (with mod_rewrite enabled), Nginx, or PHP CLI built-in web server.
  • PHP Version: PHP 7.4 or PHP 8.x (tested on 8.0, 8.1, 8.2, 8.3).
  • Required PHP Extensions: mysqli, json, session, mbstring, gd (optional, for favicon resolution verification).
  • Database: MySQL 5.7+ or MariaDB 10.3+.
  • File Permissions: Write permissions for the web server user on blocknotes/, config/, and assets/img/.

Installation & Setup Guide

1. Clone Repository or Download Release

Download the project ZIP archive or clone the Git repository onto your server:

git clone https://gitea.sld-server.org/sld-admin/sld-blocknotes.git
cd sld-blocknotes

2. Configure Directory Permissions

Ensure your web server user (such as www-data on Debian/Ubuntu or nginx on CentOS/RHEL) has write access to the storage directories:

chmod -R 775 blocknotes/ config/ assets/img/
chown -R www-data:www-data .

3. Start Web Server

For local development or testing, you can launch PHP's built-in web server:

php -S localhost:8000

4. Run First Start Setup Wizard

Open your browser and navigate to the site URL (e.g. http://localhost:8000/ or http://your-domain.com/). The application will automatically launch the setup installer first_start.php:

  1. MySQL Database Credentials: Enter your MySQL Host (e.g. localhost), Database Name (e.g. sld_blocknotes), Username, and Password. If the database does not exist, the installer will attempt to create it.
  2. Owner Account (Super-Admin): Set the username and password for the primary Owner account. This account possesses absolute privileges and cannot be deleted.
  3. First Admin Account: Set the username and password for the first secondary administrator.
  4. Complete Setup: Click ⚡ Complete Installation & Configure System. The wizard will create config/settings.php, generate the config/installed.lock security file, and redirect you to the login page.

Feature Deep Dive

1. Collapsible Notes & Visual Organization

Inside each blocknote, note items are rendered as collapsible blocks that start in a collapsed state. This design allows users to manage dozens of technical procedures without cluttering the screen.

  • Clicking any note header toggles its expansion with a smooth CSS transition.
  • Use the top navigation buttons "Expand All" and "Collapse All" to open or close every note block at once.

2. Terminal Command Subnotes & 1-Click Copy

Subnotes support two distinct display modes:

  • Standard Text: Formatted for explanatory notes, guidelines, and documentation text.
  • Terminal Command: Displayed inside a high-contrast dark console box with monospace typography. Includes a dedicated Copy button in the upper right corner that immediately copies the command string to the clipboard with visual feedback (✓ Copied!).

3. Real-Time Live Search

The search bar located at the top of the blocknote view allows instant keyword filtering. As you type, the client-side JavaScript engine searches across:

  • Parent note titles and descriptions.
  • Subnote titles.
  • Terminal command contents and code snippets.

Matching notes remain visible and are automatically expanded so you can locate the desired command or snippet instantly.

4. JSON Export & Import

Every blocknote is saved independently in blocknotes/[id].json. Through the action toolbar, you can:

  • Export Blocknote (Download JSON): Download the active blocknote as a standalone .json file for backups or transferring to another server.
  • Import JSON: Upload an external blocknote JSON file. The importer handles both standard format files and legacy array-based schemas seamlessly.

User Roles & Access Control

Role Permissions & Capabilities
Owner Full control over the system. Can manage all blocknotes, create/edit/delete admins and standard users, change the Global Application Title, and upload custom Favicons. Immune to deletion and role demotion.
Admin Can view and manage all blocknotes across the system and manage standard users. Cannot delete or alter the Owner account and cannot modify Owner-only site settings.
User Can create, edit, and delete their own personal blocknotes, and manage their personal profile settings (password, language, theme colors, default landing page).

Personalization & HSL Themes

Each user can configure their workspace from the Profile page (?page=profile):

  • Primary, Secondary & Tertiary Hue Angles: Fine-tune the HSL color palette to suit individual aesthetic preferences.
  • Preferred Language: Select between English, Italian, Spanish, and French.
  • Default Landing Page: Choose between opening the Main Dashboard or launching directly into a specific Blocknote upon login.

Blocknote JSON Schema

Example of a standard JSON file saved in the blocknotes/ directory:

{
  "id": "bn_66cb12345678a",
  "title": "Server Administration Notes",
  "description": "Essential commands and procedures for Linux server maintenance",
  "username": "admin",
  "created_at": "2026-08-25 15:30:00",
  "updated_at": "2026-08-26 10:15:00",
  "notes": [
    {
      "id": "note_66cb12998765b",
      "title": "Systemd Service Management",
      "description": "Core commands for checking and managing system daemons",
      "subnotes": [
        {
          "id": "sub_66cb1300a1b2c",
          "title": "Check Nginx Daemon Status",
          "type": "command",
          "content": "sudo systemctl status nginx --no-pager -l"
        },
        {
          "id": "sub_66cb1300d3e4f",
          "title": "Reload Configuration Notes",
          "type": "text",
          "content": "Always test configuration syntax with nginx -t before issuing a reload."
        }
      ]
    }
  ]
}

License & Information

SLD-Blocknotes is released as open-source software under the MIT License.

Official Repository: https://gitea.sld-server.org/sld-admin/sld-blocknotes