@romansmirnov/doku 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Smirnov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+<p align="center">
+  <img src="doku.png" alt="Doku" width="128" />
+</p>
+
+# Doku
+
+A personal documentation system that stores docs as plain Markdown files and provides a web UI with hierarchical navigation, WYSIWYG editing, and full-text search.
+
+## Features
+
+- **Markdown-first** — all documents are standard `.md` files on disk, editable with any tool
+- **WYSIWYG editor** — Notion-style block editor (BlockNote) with no raw Markdown editing
+- **Hierarchical folders** — organize docs in nested folders with a collapsible sidebar tree
+- **Full-text search** — instant search across all documents with highlighted snippets
+- **Auto-save** — changes save automatically (1-second debounce)
+- **Dark mode** — toggle between light and dark themes
+- **Image support** — drag and drop images into documents
+- **Frontmatter** — YAML metadata for ordering and other settings (hidden in the editor)
+- **Breadcrumb navigation** — clickable path segments to navigate parent pages
+- **Resizable sidebar** — drag the edge to adjust sidebar width
+- **No database** — the filesystem is the single source of truth
+
+## Quick Start
+
+```bash
+# Initialize a new docs folder
+npx @romansmirnov/doku init ./my-docs
+
+# Start the server
+npx @romansmirnov/doku ./my-docs
+```
+
+Open `http://localhost:4782` in your browser.
+
+## Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/romasm/Doku.git
+cd Doku
+npm install
+git submodule update --init
+
+# Start in development mode (two terminals)
+node server/index.js          # Backend on port 4782
+npx vite                      # Frontend on port 5173 with hot reload
+
+# Or build and run in production
+open_docs.bat                 # Windows
+./open_docs.sh                # macOS/Linux
+```
+
+## Configuration
+
+Place a `config.json` inside your docs folder:
+
+```json
+{
+  "projectName": "My Knowledge Base",
+  "port": 4782
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| projectName | string | "Doku" | Name displayed at the top of the sidebar |
+| port | number | 4782 | Port the backend server listens on (also overridable via `PORT` env var) |
+
+## Folder Convention
+
+Doku uses a sibling-file convention for folders:
+
+```
+docs/
+├── getting-started.md        # standalone document
+├── guides.md                 # folder index (sibling of guides/)
+├── guides/
+│   ├── writing-docs.md
+│   └── organizing-content.md
+├── config.json               # project configuration
+└── assets/                   # uploaded images
+```
+
+- Every folder needs a sibling `.md` file with the same name as its index page
+- Click **+** on any document to convert it into a folder with a child doc
+- When the last child is deleted, the empty folder is automatically removed
+
+## Frontmatter
+
+Documents support optional YAML frontmatter for metadata:
+
+```markdown
+---
+ordering: 1
+---
+# My Document
+
+Content here...
+```
+
+- `ordering` — controls position in the sidebar (lower values first, unordered items last)
+- Frontmatter is completely hidden in the editor UI and preserved on save
+
+## Tech Stack
+
+- **Backend:** Node.js, Express 5
+- **Frontend:** React 19, Vite 8, React Router v7
+- **Editor:** BlockNote with Mantine
+- **Icons:** Animated SVG icons ([pqoqubbw/icons](https://github.com/pqoqubbw/icons))
+
+## License
+
+MIT

package/bin/doku.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const command = process.argv[2];
+
+if (command === 'init') {
+  require('./init');
+} else if (command === 'help' || command === '--help' || command === '-h') {
+  console.log(`
+Doku — personal documentation system
+
+Usage:
+  doku init <path>    Initialize a new docs folder
+  doku [path]         Start the server (default: ./docs)
+  doku help           Show this help message
+
+Examples:
+  doku init ./my-docs
+  doku ./my-docs
+  doku
+`);
+} else {
+  // Treat argument as docs path, start the server
+  const docsPath = command || './docs';
+
+  // Set the docs path as argv[2] for the server config loader
+  process.argv[2] = docsPath;
+
+  // Resolve paths relative to CWD
+  const serverPath = path.join(__dirname, '..', 'server', 'index.js');
+  require(serverPath);
+}

package/bin/init.js

@@ -0,0 +1,71 @@
+const fs = require('fs');
+const path = require('path');
+
+const targetArg = process.argv[3];
+
+if (!targetArg) {
+  console.error('Usage: doku init <path>');
+  console.error('Example: doku init ./my-docs');
+  process.exit(1);
+}
+
+const targetDir = path.resolve(process.cwd(), targetArg);
+const dirName = path.basename(targetDir);
+const projectName = dirName
+  .replace(/[-_]/g, ' ')
+  .replace(/\b\w/g, (c) => c.toUpperCase());
+
+// Create directory
+if (!fs.existsSync(targetDir)) {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+// Create assets directory
+const assetsDir = path.join(targetDir, 'assets');
+if (!fs.existsSync(assetsDir)) {
+  fs.mkdirSync(assetsDir, { recursive: true });
+}
+
+// Create config.json
+const configPath = path.join(targetDir, 'config.json');
+if (!fs.existsSync(configPath)) {
+  fs.writeFileSync(configPath, JSON.stringify({
+    projectName,
+    port: 4782,
+  }, null, 2) + '\n');
+}
+
+// Create sample getting-started.md
+const sampleDoc = path.join(targetDir, 'getting-started.md');
+if (!fs.existsSync(sampleDoc)) {
+  fs.writeFileSync(sampleDoc, `---
+ordering: 1
+---
+# Getting Started
+
+Welcome to **${projectName}**.
+
+This is your first document. You can edit it using the web UI or any text editor.
+
+## Next Steps
+
+- Edit this document to add your own content
+- Click the **+** button in the sidebar to create new documents
+- Organize documents into folders by clicking **+** on any existing document
+- Use the search bar to find content across all documents
+- Toggle dark mode with the button at the bottom of the sidebar
+`);
+}
+
+console.log(`
+  Doku initialized in ${targetDir}
+
+  Project name: ${projectName}
+  Port: 4782
+
+  To start:
+    npx @romansmirnov/doku ${targetArg}
+
+  Or with the convenience script:
+    open_docs.bat ${targetArg}
+`);

package/client/src/lib/utils.js

@@ -0,0 +1,4 @@
+// Minimal cn() shim — joins class names, filtering out falsy values
+export function cn(...inputs) {
+  return inputs.filter(Boolean).join(' ');
+}