living-documentation 2.0.0 → 3.2.0

package/README.md

@@ -10,7 +10,8 @@ No cloud, no database, no build step — just point it at a folder of `.md` file
 
 ## Features
 
-- **Sidebar** grouped by category, sorted by date (newest first)
+- **Sidebar** grouped by category, sorted alphabetically by full filename
+- **Recursive folder scanning** — subdirectories are scanned automatically; subdirectory name becomes the category
 - **General section** — always first, always expanded; holds uncategorized docs and extra files
 - **Extra files** — include Markdown files from outside the docs folder (e.g. `README.md`, `CLAUDE.md`)
 - **Full-text search** — instant filter + server-side content search
@@ -19,6 +20,8 @@ No cloud, no database, no build step — just point it at a folder of `.md` file
 - **Export to PDF** — print-friendly layout via `window.print()`
 - **Deep links** — share a direct URL to any document (`?doc=…`)
 - **Admin panel** — configure title, theme, filename pattern, and extra files in the browser
+- **Inline editing** — edit any document directly in the browser, saves to disk instantly
+- **Image paste** — paste an image from clipboard in the editor; auto-uploaded and inserted as Markdown
 - **Zero frontend build** — Tailwind and highlight.js loaded from CDN
 
 ---
@@ -108,6 +111,25 @@ YYYY_MM_DD_[Category]_title_words.md
 
 Files that don't match the pattern are still shown — they appear under **General** with the filename as the title.
 
+### Subdirectories
+
+The docs folder is scanned **recursively**. Files in subdirectories are automatically discovered:
+
+- If the filename matches the pattern (contains `[Category]`), the category from the filename is used.
+- Otherwise, the **subdirectory name** becomes the category.
+
+```
+docs/
+├── 2024_01_15_[DevOps]_deploy.md      → category: DevOps
+├── adrs/
+│   ├── my-decision.md                 → category: Adrs
+│   └── 2024_03_01_[Architecture]_event_sourcing.md  → category: Architecture
+└── guides/
+    └── onboarding.md                  → category: Guides
+```
+
+The pattern is **configurable** in the Admin panel. Token order is respected — `[Category]_YYYY_MM_DD_title` is valid. `[Category]` must appear exactly once.
+
 ---
 
 ## Config file
@@ -153,9 +175,10 @@ living-documentation/
 ├── src/
 │   ├── server.ts            Express app
 │   ├── routes/
-│   │   ├── documents.ts     Documents API
+│   │   ├── documents.ts     Documents API (list, search, read, write)
 │   │   ├── config.ts        Config API
-│   │   └── browse.ts        Filesystem browser API
+│   │   ├── browse.ts        Filesystem browser API
+│   │   └── images.ts        Image upload API
 │   ├── lib/
 │   │   ├── parser.ts        Filename parser
 │   │   └── config.ts        Config management
@@ -176,10 +199,12 @@ living-documentation/
 | ------ | -------------------------- | ------------------------------------------------------------------ |
 | `GET`  | `/api/documents`           | List all documents with metadata (includes extra files)            |
 | `GET`  | `/api/documents/:id`       | Get document content + rendered HTML                               |
+| `PUT`  | `/api/documents/:id`       | Save document content to disk                                      |
 | `GET`  | `/api/documents/search?q=` | Full-text search                                                   |
 | `GET`  | `/api/config`              | Read config                                                        |
 | `PUT`  | `/api/config`              | Update config (`title`, `theme`, `filenamePattern`, `extraFiles`)  |
 | `GET`  | `/api/browse?path=`        | List directories and `.md` files at a given filesystem path        |
+| `POST` | `/api/images/upload`       | Upload a base64 image; saved to `DOCS_FOLDER/images/`             |
 
 ---
 

package/dist/src/frontend/index.html

@@ -13,6 +13,9 @@
         href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css" />
   <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
 
+  <!-- WordCloud2.js — vendored from npm, no CDN dependency -->
+  <script src="/vendor/wordcloud2.js"></script>
+
   <script>
     tailwind.config = {
       darkMode: 'class',
@@ -102,6 +105,12 @@
         <span id="dark-icon" class="text-lg leading-none">&#9790;</span>
       </button>
 
+      <!-- Word Cloud -->
+      <button onclick="openWordCloud()"
+              class="text-sm px-3 py-1.5 rounded-lg text-gray-600 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors font-medium">
+        &#9729; Word Cloud
+      </button>
+
       <!-- Admin link -->
       <a href="/admin"
          class="text-sm px-3 py-1.5 rounded-lg text-gray-600 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors font-medium">
@@ -236,6 +245,21 @@
   </div><!-- end body row -->
 </div><!-- end root -->
 
+<!-- ── Word Cloud overlay ── -->
+<div id="wc-overlay" class="hidden fixed inset-0 z-50 flex flex-col bg-white dark:bg-gray-950">
+  <div class="flex items-center justify-between px-6 h-14 border-b border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 shrink-0">
+    <h2 class="font-semibold text-base">&#9729; Word Cloud</h2>
+    <button onclick="closeWordCloud()"
+            class="text-sm px-3 py-1.5 rounded-lg text-gray-600 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors">
+      &#10005; Close
+    </button>
+  </div>
+  <div id="wc-body" class="flex-1 relative overflow-hidden flex items-center justify-center">
+    <p id="wc-status" class="text-gray-400 dark:text-gray-500 text-sm animate-pulse"></p>
+    <canvas id="wc-canvas" class="hidden absolute inset-0 w-full h-full"></canvas>
+  </div>
+</div>
+
 <script>
 // ── State ──────────────────────────────────────────────────
 let allDocs = [];
@@ -638,6 +662,105 @@ function esc(str) {
     .replace(/'/g, '&#39;');
 }
 
+// ── Word Cloud ─────────────────────────────────────────────
+const WC_STOP_WORDS = new Set([
+  // English
+  'the','and','for','are','but','not','you','all','this','that','with','have','from',
+  'they','will','one','been','can','has','was','more','also','when','there','their',
+  'what','about','which','would','into','than','then','each','just','over','after',
+  'such','here','its','your','our','some','were','very','only','out','had','she',
+  'his','her','him','who','how','any','other','these','those','being','may','use',
+  'used','using','should','could','would','shall','must','need','via','per','like',
+  // French
+  'les','des','une','pour','pas','sur','par','est','qui','que','dans','avec','sont',
+  'plus','tout','aux','mais','comme','vous','nous','leur','lui','elle','ils','elles',
+  'ces','ses','mon','ton','son','mes','tes','ainsi','donc','alors','car','peut','fait',
+  'encore','bien','aussi','très','même','entre','vers','dont','sans','sous',
+]);
+
+async function openWordCloud() {
+  const overlay = document.getElementById('wc-overlay');
+  const status = document.getElementById('wc-status');
+  const canvas = document.getElementById('wc-canvas');
+  overlay.classList.remove('hidden');
+  status.textContent = 'Loading documents…';
+  status.classList.remove('hidden');
+  canvas.classList.add('hidden');
+
+  try {
+    const docs = allDocs.length ? allDocs : await fetch('/api/documents').then(r => r.json());
+    status.textContent = `Analyzing ${docs.length} documents…`;
+
+    const results = await Promise.all(
+      docs.map(doc => fetch('/api/documents/' + doc.id).then(r => r.ok ? r.json() : null).catch(() => null))
+    );
+
+    const freq = {};
+    for (const doc of results) {
+      if (!doc?.content) continue;
+      for (const w of extractWordsFromMarkdown(doc.content)) {
+        freq[w] = (freq[w] || 0) + 1;
+      }
+    }
+
+    const list = Object.entries(freq)
+      .filter(([, n]) => n >= 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 150);
+
+    if (!list.length) { status.textContent = 'Not enough words found.'; return; }
+
+    renderWordCloud(list);
+  } catch (err) {
+    status.textContent = 'Error: ' + err.message;
+  }
+}
+
+function extractWordsFromMarkdown(text) {
+  return text
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]+`/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, '')
+    .replace(/[#*_~>`|!\[\](){}=\-+]/g, ' ')
+    .toLowerCase()
+    .split(/[^a-zàâäéèêëïîôùûü']+/)
+    .map(w => w.replace(/^'+|'+$/g, ''))
+    .filter(w => w.length > 3 && !WC_STOP_WORDS.has(w));
+}
+
+function renderWordCloud(list) {
+  const canvas = document.getElementById('wc-canvas');
+  const body = document.getElementById('wc-body');
+  canvas.width = body.clientWidth;
+  canvas.height = body.clientHeight;
+
+  const isDark = document.documentElement.classList.contains('dark');
+  const colors = isDark
+    ? ['#60a5fa','#34d399','#f9a8d4','#a78bfa','#fbbf24','#6ee7b7','#93c5fd','#fb923c']
+    : ['#1d4ed8','#047857','#7c3aed','#b45309','#be123c','#0369a1','#4338ca','#c2410c'];
+
+  const maxFreq = list[0][1];
+  const wordList = list.map(([w, n]) => [w, Math.max(10, Math.round(72 * n / maxFreq))]);
+
+  document.getElementById('wc-status').classList.add('hidden');
+  canvas.classList.remove('hidden');
+
+  WordCloud(canvas, {
+    list: wordList,
+    gridSize: Math.round(8 * canvas.width / 1024),
+    fontFamily: 'ui-sans-serif, system-ui, sans-serif',
+    color: () => colors[Math.floor(Math.random() * colors.length)],
+    backgroundColor: isDark ? '#030712' : '#ffffff',
+    rotateRatio: 0.3,
+    minSize: 10,
+  });
+}
+
+function closeWordCloud() {
+  document.getElementById('wc-overlay').classList.add('hidden');
+}
+
 // Browser back/forward
 window.addEventListener('popstate', e => {
   const id = e.state?.docId || new URLSearchParams(location.search).get('doc');