retold-content-system 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steven Velozo
+
+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,107 @@
+# Retold Content System
+
+A markdown content editor and documentation viewer built on the [Retold](https://github.com/stevenvelozo/retold) ecosystem. Point it at any folder of markdown files and get a local editing environment with a file browser, rich markdown editor, syntax-highlighted code editor, live preview, image uploads, and documentation topics management.
+
+## Install
+
+```bash
+npm install -g retold-content-system
+```
+
+## Quick Start
+
+```bash
+mkdir my-docs && cd my-docs
+echo "# Hello" > README.md
+rcs serve
+```
+
+Open the printed URL in your browser. The reader is at `/` and the editor is at `/edit.html`.
+
+## CLI
+
+The package installs two equivalent commands: `retold-content-system` and `rcs`.
+
+### `rcs serve [content-path] [-p port]`
+
+Start the content system server.
+
+| Argument / Option | Description |
+|-------------------|-------------|
+| `[content-path]` | Path to the content folder (default: current directory) |
+| `-p, --port` | Port number (default: random 7000-7999) |
+
+```bash
+# Serve current directory on a random port
+rcs serve
+
+# Serve a specific folder on port 8080
+rcs serve ~/my-wiki -p 8080
+```
+
+If the directory contains a `content/` subfolder, it is used automatically.
+
+## Editor Features
+
+- **File Browser** -- Tree view sidebar with folder navigation, new file creation, and image uploads
+- **Markdown Editor** -- CodeMirror-based editor with formatting toolbar, auto-segmentation at heading boundaries, and word wrap
+- **Code Editor** -- CodeJar + highlight.js editor for JSON, HTML, CSS, YAML, and 190+ languages
+- **Live Preview** -- Reference panel showing rendered markdown, toggled with F1
+- **Topics Panel** -- Manage `.pict_documentation_topics.json` manifests linking topic codes to files and line numbers
+- **Settings** -- Configurable segmentation depth, word wrap, media preview, hidden files, and more (persisted in localStorage)
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd/Ctrl+S` | Save |
+| `Escape` | Close file (with unsaved-changes confirmation) |
+| `F1` | Toggle Reference panel |
+| `F2` | Toggle sidebar |
+| `F3` / `Cmd/Ctrl+Shift+U` | Upload image |
+| `F4` / `Cmd/Ctrl+Shift+T` | Topics tab (creates linked topic from cursor in markdown) |
+
+## Documentation Reader
+
+The root URL (`/`) serves a pict-docuserve documentation viewer. If your content folder includes `cover.md`, `_sidebar.md`, and `_topbar.md`, the reader uses them for navigation. Otherwise it renders markdown files directly.
+
+## Architecture
+
+Built on these Retold modules:
+
+- **[Orator](https://github.com/stevenvelozo/orator)** -- HTTP server with Restify
+- **[Pict](https://github.com/stevenvelozo/pict)** -- MVC framework for the browser applications
+- **[pict-docuserve](https://github.com/stevenvelozo/pict-docuserve)** -- Documentation reader/viewer
+- **[pict-section-markdowneditor](https://github.com/stevenvelozo/pict-section-markdowneditor)** -- CodeMirror markdown editor component
+- **[pict-section-code](https://github.com/stevenvelozo/pict-section-code)** -- CodeJar code editor component
+- **[pict-section-filebrowser](https://github.com/stevenvelozo/pict-section-filebrowser)** -- File browser component
+- **[pict-service-commandlineutility](https://github.com/stevenvelozo/pict-service-commandlineutility)** -- CLI framework
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/stevenvelozo/retold.git
+cd retold/app/retold-content-system
+npm install
+
+# Build everything (CodeMirror bundle, CodeJar bundle, application bundle)
+npm run build-all
+
+# Start the dev server
+npm start
+```
+
+The build uses [Quackage](https://github.com/stevenvelozo/quackage) for the main application bundle and esbuild for the CodeMirror and CodeJar editor bundles.
+
+## Documentation
+
+Full documentation is in the `docs/` folder and can be viewed with the content system itself:
+
+```bash
+rcs serve docs/
+```
+
+## License
+
+MIT

package/build-codejar-bundle.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Build script to bundle CodeJar + highlight.js into a single browser-compatible file.
+ * Run: node build-codejar-bundle.js
+ *
+ * This creates html/codejar-bundle.js which exposes window.CodeJarModules
+ * with { CodeJar, hljs }.
+ */
+const { build } = require('esbuild');
+const path = require('path');
+
+build(
+{
+	entryPoints: [path.join(__dirname, 'codejar-entry.js')],
+	bundle: true,
+	outfile: path.join(__dirname, 'html', 'codejar-bundle.js'),
+	format: 'iife',
+	globalName: 'CodeJarModules',
+	platform: 'browser',
+	target: ['es2018'],
+	minify: true
+}).then(() =>
+{
+	console.log('CodeJar + highlight.js bundle built successfully -> html/codejar-bundle.js');
+}).catch((pError) =>
+{
+	console.error('Build failed:', pError);
+	process.exit(1);
+});

package/build-codemirror-bundle.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Build script to bundle CodeMirror v6 into a single browser-compatible file.
+ * Run: node build-codemirror-bundle.js
+ *
+ * This creates html/codemirror-bundle.js which exposes window.CodeMirrorModules
+ * with { EditorView, EditorState, Decoration, ViewPlugin, WidgetType, extensions }.
+ */
+const { build } = require('esbuild');
+const path = require('path');
+
+build(
+{
+	entryPoints: [path.join(__dirname, 'codemirror-entry.js')],
+	bundle: true,
+	outfile: path.join(__dirname, 'html', 'codemirror-bundle.js'),
+	format: 'iife',
+	globalName: 'CodeMirrorModules',
+	platform: 'browser',
+	target: ['es2018'],
+	minify: false
+}).then(() =>
+{
+	console.log('CodeMirror bundle built successfully -> html/codemirror-bundle.js');
+}).catch((pError) =>
+{
+	console.error('Build failed:', pError);
+	process.exit(1);
+});

package/codejar-entry.js

@@ -0,0 +1,10 @@
+/**
+ * CodeJar + highlight.js entry point for browser bundling.
+ *
+ * This file is bundled by esbuild into a single script that sets
+ * window.CodeJar and window.hljs for the code editor.
+ */
+import { CodeJar } from 'codejar';
+import hljs from 'highlight.js';
+
+export { CodeJar, hljs };

package/codemirror-entry.js

@@ -0,0 +1,16 @@
+/**
+ * CodeMirror v6 entry point for browser bundling.
+ *
+ * This file is bundled by esbuild into a single script that sets
+ * window.CodeMirrorModules with everything the markdown editor needs.
+ */
+import { EditorView, basicSetup } from 'codemirror';
+import { EditorState } from '@codemirror/state';
+import { Decoration, ViewPlugin, WidgetType } from '@codemirror/view';
+import { markdown } from '@codemirror/lang-markdown';
+
+// Export everything the editor needs
+export { EditorView, EditorState, Decoration, ViewPlugin, WidgetType, basicSetup, markdown };
+
+// Also set up the extensions array that the editor expects
+export const extensions = [basicSetup, markdown()];

package/content/Dogs.txt.md

@@ -0,0 +1,2 @@
+# Dogs.txt
+

package/content/README.md

@@ -0,0 +1,35 @@
+# Retold Content System
+
+The Retold Content System is a markdown-based content management application built on the Retold ecosystem.
+
+## Features
+
+- **Reader Modereo** — Renders markdown content with full styling, code highlighting, and sidebar navigation
+- **Editor Mode** — Edit markdown content in-place using a segmented CodeMirror-based editor
+- **Image Upload** — Drag, paste, or pick images; they upload to the server and insert as URLs
+- **Live Preview** — See rendered markdown alongside the editor in real-time
+- **File Management** — Browse and edit any markdown file in the content directory
+
+## Architecture
+
+The system combines two Retold components:
+
+1. **Orator** — A Node.js web server (built on Restify) that serves static files and provides REST APIs for content management
+2. **Pict** — A browser-side MVC framework that powers both the reader and editor applications
+
+The reader application extends `pict-docuserve` for documentation viewing. The editor application uses `pict-section-markdowneditor` for markdown editing.
+
+## Quick Start
+
+```bash
+cd app/retold-content-system
+npm install
+npm run build-all
+npm start
+```
+
+![Squirrel-003-Processed-10k](/uploads/1771723928061-Squirrel-003-Processed-10k.png)
+
+Then open:
+- Reader: http://localhost:8086/
+- Editor: http://localhost:8086/edit.html

package/content/_sidebar.md

@@ -0,0 +1,3 @@
+- Content
+  - [README](README.md)
+  - [Getting Started](getting-started.md)

package/content/_topbar.md

@@ -0,0 +1 @@
+# Content System

package/content/cover.md

@@ -0,0 +1,12 @@
+# Retold Content System
+
+> A markdown content management system built on Pict and Orator
+
+Browse and edit your documentation content through a web browser. View beautifully rendered markdown or switch to the editor for in-place editing with image upload support.
+
+- **Reader Mode** — Clean, fast documentation viewer with sidebar navigation
+- **Editor Mode** — Full markdown editor with live preview, image upload, and segment management
+- **Server-Backed** — Content persisted to disk, images uploaded and served automatically
+
+[Get Started](getting-started.md)
+[View README](README.md)

package/content/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+## Prerequisites
+
+- brain
+- heart
+- liver
+- moxie
+
+## Installation
+
+Clone the retold monorepo and navigate to the content system:
+
+```bash
+cd app/retold-content-system
+npm install
+```
+
+## Building
+
+Build the CodeMirror bundle, reader application, and editor application:
+
+```bash
+npm run build-all
+```
+
+Or build components individually:
+
+```bash
+npm run build-codemirror   # Build CodeMirror bundle for the editor
+npm run build              # Build the reader application
+npm run build-editor       # Build the editor application
+```
+
+## Running
+
+Start the server:
+
+```bash
+npm start
+```
+
+The server starts on port 8086 by default. Open your browser to:
+
+- **Reader:** http://localhost:8086/
+- **Editor:** http://localhost:8086/edit.html
+
+## Content Directory
+
+Markdown files live in the `content/` directory. The reader serves them as documentation pages. The editor lets you modify them in-place.
+
+Special files:
+- `cover.md` — Splash page content
+- `_sidebar.md` — Sidebar navigation structure
+- `_topbar.md` — Header bar branding and navigation
+- `README.md` — Default documentation page
+
+## Editing Content
+
+1. Navigate to the editor at `/edit.html`
+2. Select a file from the sidebar
+3. Edit the markdown content in the segmented editor
+4. Click Save to persist changes to disk
+5. Switch back to the reader to see the rendered result
+
+## Image Uploads
+
+Images can be added to documents in the editor by:
+- Dragging an image file onto the editor
+- Pasting an image from the clipboard
+- Clicking the image button in the editor toolbar
+
+Images are uploaded to the server and stored in the `uploads/` directory. The editor inserts a URL reference (not base64) to keep documents lightweight.

package/css/content-system.css

@@ -0,0 +1,42 @@
+/* Retold Content System — Base Styles */
+
+*, *::before, *::after
+{
+	box-sizing: border-box;
+}
+
+html
+{
+	font-size: 16px;
+	-webkit-text-size-adjust: 100%;
+}
+
+body
+{
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+	background: #FAF8F4;
+	color: #423D37;
+	line-height: 1.6;
+}
+
+/* Scrollbar styling */
+::-webkit-scrollbar
+{
+	width: 8px;
+	height: 8px;
+}
+::-webkit-scrollbar-track
+{
+	background: #F5F0E8;
+}
+::-webkit-scrollbar-thumb
+{
+	background: #C4BDB0;
+	border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover
+{
+	background: #8A7F72;
+}

package/css/github.css

@@ -0,0 +1,118 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+  Theme: GitHub
+  Description: Light theme as seen on github.com
+  Author: github.com
+  Maintainer: @Hirse
+  Updated: 2021-05-15
+
+  Outdated base version: https://github.com/primer/github-syntax-light
+  Current colors taken from GitHub's CSS
+*/
+.hljs {
+  color: #24292e;
+  background: #ffffff
+}
+.hljs-doctag,
+.hljs-keyword,
+.hljs-meta .hljs-keyword,
+.hljs-template-tag,
+.hljs-template-variable,
+.hljs-type,
+.hljs-variable.language_ {
+  /* prettylights-syntax-keyword */
+  color: #d73a49
+}
+.hljs-title,
+.hljs-title.class_,
+.hljs-title.class_.inherited__,
+.hljs-title.function_ {
+  /* prettylights-syntax-entity */
+  color: #6f42c1
+}
+.hljs-attr,
+.hljs-attribute,
+.hljs-literal,
+.hljs-meta,
+.hljs-number,
+.hljs-operator,
+.hljs-variable,
+.hljs-selector-attr,
+.hljs-selector-class,
+.hljs-selector-id {
+  /* prettylights-syntax-constant */
+  color: #005cc5
+}
+.hljs-regexp,
+.hljs-string,
+.hljs-meta .hljs-string {
+  /* prettylights-syntax-string */
+  color: #032f62
+}
+.hljs-built_in,
+.hljs-symbol {
+  /* prettylights-syntax-variable */
+  color: #e36209
+}
+.hljs-comment,
+.hljs-code,
+.hljs-formula {
+  /* prettylights-syntax-comment */
+  color: #6a737d
+}
+.hljs-name,
+.hljs-quote,
+.hljs-selector-tag,
+.hljs-selector-pseudo {
+  /* prettylights-syntax-entity-tag */
+  color: #22863a
+}
+.hljs-subst {
+  /* prettylights-syntax-storage-modifier-import */
+  color: #24292e
+}
+.hljs-section {
+  /* prettylights-syntax-markup-heading */
+  color: #005cc5;
+  font-weight: bold
+}
+.hljs-bullet {
+  /* prettylights-syntax-markup-list */
+  color: #735c0f
+}
+.hljs-emphasis {
+  /* prettylights-syntax-markup-italic */
+  color: #24292e;
+  font-style: italic
+}
+.hljs-strong {
+  /* prettylights-syntax-markup-bold */
+  color: #24292e;
+  font-weight: bold
+}
+.hljs-addition {
+  /* prettylights-syntax-markup-inserted */
+  color: #22863a;
+  background-color: #f0fff4
+}
+.hljs-deletion {
+  /* prettylights-syntax-markup-deleted */
+  color: #b31d28;
+  background-color: #ffeef0
+}
+.hljs-char.escape_,
+.hljs-link,
+.hljs-params,
+.hljs-property,
+.hljs-punctuation,
+.hljs-tag {
+  /* purposely ignored */
+  
+}

package/docs/README.md

@@ -0,0 +1,24 @@
+# Retold Content System Documentation
+
+This folder contains the pict-docuserve documentation for the Retold Content System.
+
+## Viewing the Docs
+
+These markdown files are meant to be served by pict-docuserve or by the content system itself. To view them locally:
+
+```bash
+rcs serve docs/ -p 8080
+```
+
+Then open `http://localhost:8080/` in your browser.
+
+## Contents
+
+- **getting-started.md** -- Installation, quick start, and server overview
+- **editor-guide.md** -- Walkthrough of the editor UI: file browser, markdown editor, code editor, sidebar tabs, and settings
+- **keyboard-shortcuts.md** -- Complete keyboard shortcut reference
+- **cli.md** -- CLI command reference with examples and programmatic usage
+- **topics.md** -- Documentation topics system for managing help manifests
+- **cover.md** -- Landing page for the pict-docuserve viewer
+- **_sidebar.md** -- Sidebar navigation tree
+- **_topbar.md** -- Top bar navigation

package/docs/_sidebar.md

@@ -0,0 +1,16 @@
+- Getting Started
+
+  - [Overview](getting-started.md)
+
+- Using the Editor
+
+  - [Editor Guide](editor-guide.md)
+  - [Keyboard Shortcuts](keyboard-shortcuts.md)
+
+- Command Line
+
+  - [CLI Reference](cli.md)
+
+- Topics System
+
+  - [Documentation Topics](topics.md)

package/docs/_topbar.md

@@ -0,0 +1,6 @@
+# Content System
+
+- [Getting Started](getting-started.md)
+- [Editor Guide](editor-guide.md)
+- [CLI](cli.md)
+- [GitHub](https://github.com/stevenvelozo/retold)

package/docs/cli.md

@@ -0,0 +1,119 @@
+# CLI Reference
+
+The Retold Content System installs two equivalent commands: `retold-content-system` and the shorthand `rcs`. All examples below use `rcs`.
+
+## serve
+
+Start the content system server for a content folder.
+
+```bash
+rcs serve [content-path] [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `[content-path]` | Path to the markdown content folder. Defaults to the current directory. |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port [port]` | Port to serve on. Defaults to a random port between 7000 and 7999. |
+
+### Examples
+
+**Serve the current directory on a random port:**
+
+```bash
+rcs serve
+```
+
+**Serve a specific folder on port 8080:**
+
+```bash
+rcs serve ~/my-docs -p 8080
+```
+
+**Serve a project with a content/ subfolder:**
+
+```bash
+cd ~/my-project
+rcs serve
+```
+
+If the current directory contains a `content/` subfolder, the server automatically uses that as the content root. No extra path argument is needed.
+
+### Output
+
+On startup the server prints a banner with all relevant paths and URLs:
+
+```
+  Retold Content System running on http://localhost:7042
+  Content: /Users/you/my-docs
+  Uploads: /Users/you/my-docs/uploads
+  Assets:  /path/to/retold-content-system/dist
+  Reader:  http://localhost:7042/
+  Editor:  http://localhost:7042/edit.html
+```
+
+Press `Ctrl+C` to stop the server.
+
+### Server API
+
+The server exposes a set of REST endpoints that both the reader and editor applications use:
+
+**File Browser**
+
+- `GET /api/filebrowser/list` -- List files and folders in the content directory
+- `GET /api/filebrowser/list/*` -- List files in a subdirectory
+- `PUT /api/filebrowser/settings` -- Toggle file browser options (e.g. show hidden files)
+
+**Content**
+
+- `GET /api/content/read/*` -- Read the raw content of a file
+- `PUT /api/content/save/*` -- Save content to a file (create or overwrite)
+- `POST /api/content/upload-image` -- Upload an image file into the content folder
+
+**Static Routes**
+
+- `/` -- The pict-docuserve documentation reader
+- `/edit.html` -- The content editor application
+- `/content/*` -- Raw content files served directly
+- `/uploads/*` -- Uploaded image files
+
+## Usage with npx
+
+If you prefer not to install globally, run directly with npx:
+
+```bash
+npx retold-content-system serve ~/my-docs -p 9000
+```
+
+## Programmatic Use
+
+The server setup is also available as a module for embedding in other Node.js applications:
+
+```javascript
+const setupServer = require('retold-content-system/source/cli/ContentSystem-Server-Setup.js');
+
+setupServer(
+    {
+        ContentPath: '/path/to/content',
+        UploadPath: '/path/to/content/uploads',
+        DistPath: '/path/to/retold-content-system/dist',
+        Port: 8080
+    },
+    function (pError, pServerInfo)
+    {
+        if (pError)
+        {
+            console.error('Failed to start:', pError);
+            return;
+        }
+        console.log('Server running on port', pServerInfo.Port);
+    });
+```
+
+The callback receives an object with `Fable`, `Orator`, and `Port` properties for further customization.