retold-content-system 1.0.11 → 1.0.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +130 -68
- package/package.json +4 -4
- package/source/cli/ContentSystem-Server-Setup.js +7 -3
- package/web-application/js/pict.min.js +2 -2
- package/web-application/retold-content-system.compatible.js +50 -7
- package/web-application/retold-content-system.compatible.js.map +1 -1
- package/web-application/retold-content-system.compatible.min.js +5 -5
- package/web-application/retold-content-system.compatible.min.js.map +1 -1
- package/web-application/retold-content-system.js +49 -6
- package/web-application/retold-content-system.js.map +1 -1
- package/web-application/retold-content-system.min.js +1 -1
- package/web-application/retold-content-system.min.js.map +1 -1
package/README.md
CHANGED
|
@@ -1,107 +1,169 @@
|
|
|
1
1
|
# Retold Content System
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
A full-stack markdown content editor and documentation reader. Point it at any folder of markdown files and you get a live documentation site (reader), an in-browser editor with a file browser, syntax-highlighted code editing, live markdown preview with Mermaid and KaTeX, and a drop-in CLI server. Every persistence boundary -- markdown read, markdown save, image upload, file listing -- is a named hook that developers can replace to plug the system into any backend.
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **Drop-In CLI** -- `npx rcs serve ./my-docs` starts a complete reader + editor server in seconds
|
|
12
|
+
- **Dual Applications** -- Reader (`/`) renders documentation via `pict-docuserve`; Editor (`/edit.html`) provides in-browser authoring
|
|
13
|
+
- **File Browser Sidebar** -- Tree + list views over your content folder with breadcrumbs, create-file / create-folder, hidden-file toggle, and keyboard-driven navigation
|
|
14
|
+
- **Markdown Editor** -- CodeMirror-based editor with formatting toolbar, line numbers, word wrap, and live preview side-by-side
|
|
15
|
+
- **Code Editor** -- CodeJar + highlight.js editor with syntax highlighting for 190+ languages (JS, TS, Python, Java, Go, SQL, HTML, CSS, JSON, YAML, ...)
|
|
16
|
+
- **Live Preview** -- Renders markdown with GitHub-flavored styling, Mermaid diagrams, and KaTeX equations in real time
|
|
17
|
+
- **Image Upload** -- F3 / toolbar upload places images next to the file being edited with smart filename deduping
|
|
18
|
+
- **Binary Previews** -- Images, audio, video, and document files get automatic preview cards with download and open-in-new-tab actions
|
|
19
|
+
- **Topics Manifest** -- `.pict_documentation_topics.json` links named topics to line ranges in your markdown for API-doc-style cross-references
|
|
20
|
+
- **Pluggable Persistence** -- Override `loadFile`, `saveFile`, and `uploadImage` on the client provider or replace the REST endpoints on the server to move content into a database, object store, or any other backend
|
|
21
|
+
- **Ultravisor Beacon Support** -- Optional `--beacon` mode exposes the same read / save / list / mkdir operations as workflow capabilities
|
|
22
|
+
- **Pict Native** -- Built on `pict-application`, `pict-provider`, `pict-view`, `pict-docuserve`, `pict-section-markdowneditor`, `pict-section-code`, `pict-section-filebrowser`
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
6
25
|
|
|
7
26
|
```bash
|
|
8
27
|
npm install -g retold-content-system
|
|
28
|
+
# or as a project dep
|
|
29
|
+
npm install retold-content-system
|
|
9
30
|
```
|
|
10
31
|
|
|
11
32
|
## Quick Start
|
|
12
33
|
|
|
13
34
|
```bash
|
|
14
|
-
|
|
15
|
-
echo "# Hello" > README.md
|
|
35
|
+
# Serve the current directory on a random port
|
|
16
36
|
rcs serve
|
|
17
|
-
```
|
|
18
37
|
|
|
19
|
-
|
|
38
|
+
# Serve a specific folder on a specific port
|
|
39
|
+
rcs serve ~/Documents/handbook -p 8080
|
|
20
40
|
|
|
21
|
-
|
|
41
|
+
# With Ultravisor beacon mode
|
|
42
|
+
rcs serve ./docs -b http://localhost:54321
|
|
43
|
+
```
|
|
22
44
|
|
|
23
|
-
The
|
|
45
|
+
The CLI prints the URL once it's ready:
|
|
24
46
|
|
|
25
|
-
|
|
47
|
+
```
|
|
48
|
+
==========================================================
|
|
49
|
+
Retold Content System running on http://localhost:7234
|
|
50
|
+
==========================================================
|
|
51
|
+
Content: /Users/steven/Documents/handbook
|
|
52
|
+
==========================================================
|
|
53
|
+
```
|
|
26
54
|
|
|
27
|
-
|
|
55
|
+
Open `/` for the reader or `/edit.html` for the editor.
|
|
56
|
+
|
|
57
|
+
## CLI Reference
|
|
58
|
+
|
|
59
|
+
| Command | Description |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `rcs serve [path]` | Start the server. `path` defaults to the current directory (or `./content/` if that exists). |
|
|
62
|
+
| `-p, --port <port>` | TCP port. Defaults to a random port in 7000-7999. |
|
|
63
|
+
| `-b, --beacon <url>` | Connect to an Ultravisor server at `<url>` and register content capabilities. |
|
|
64
|
+
| `--beacon-name <name>` | Beacon worker identity (default `content-system-1`). |
|
|
65
|
+
| `--beacon-password <password>` | Beacon authentication password. |
|
|
66
|
+
|
|
67
|
+
See [docs/cli-reference.md](docs/cli-reference.md) for the full reference.
|
|
68
|
+
|
|
69
|
+
## Pluggable Persistence
|
|
70
|
+
|
|
71
|
+
Every place the system touches storage is a named, overridable boundary. On the client, `ContentEditorProvider` exposes three methods -- `loadFile`, `saveFile`, `uploadImage` -- that you can replace by registering a subclass. On the server, each REST endpoint (`/api/content/read/*`, `/api/content/save/*`, `/api/content/upload-image`, `/api/content/mkdir`) is a standard Orator route you can swap out for a database, S3, or any HTTP backend.
|
|
72
|
+
|
|
73
|
+
```javascript
|
|
74
|
+
const libPictProvider = require('pict-provider');
|
|
75
|
+
|
|
76
|
+
class S3ContentProvider extends libPictProvider
|
|
77
|
+
{
|
|
78
|
+
loadFile(pFilePath, fCallback)
|
|
79
|
+
{
|
|
80
|
+
this.s3.getObject({ Bucket: 'docs', Key: pFilePath }, (err, data) =>
|
|
81
|
+
{
|
|
82
|
+
if (err) return fCallback(err.message, '');
|
|
83
|
+
return fCallback(null, data.Body.toString('utf8'));
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
saveFile(pFilePath, pContent, fCallback)
|
|
88
|
+
{
|
|
89
|
+
this.s3.putObject({ Bucket: 'docs', Key: pFilePath, Body: pContent }, (err) =>
|
|
90
|
+
fCallback(err ? err.message : null));
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
uploadImage(pFile, fCallback)
|
|
94
|
+
{
|
|
95
|
+
this.s3.putObject({ Bucket: 'images', Key: pFile.name, Body: pFile }, (err) =>
|
|
96
|
+
{
|
|
97
|
+
if (err) return fCallback(err.message);
|
|
98
|
+
return fCallback(null, `https://cdn.example.com/images/${ pFile.name }`);
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
```
|
|
28
103
|
|
|
29
|
-
|
|
30
|
-
|-------------------|-------------|
|
|
31
|
-
| `[content-path]` | Path to the content folder (default: current directory) |
|
|
32
|
-
| `-p, --port` | Port number (default: random 7000-7999) |
|
|
104
|
+
See [docs/persistence-hooks.md](docs/persistence-hooks.md) for every extension point, including image storage strategies, database-backed examples, and server-side middleware patterns.
|
|
33
105
|
|
|
34
|
-
|
|
35
|
-
# Serve current directory on a random port
|
|
36
|
-
rcs serve
|
|
106
|
+
## Content Folder Conventions
|
|
37
107
|
|
|
38
|
-
|
|
39
|
-
|
|
108
|
+
```
|
|
109
|
+
my-docs/
|
|
110
|
+
├── README.md # reader home page
|
|
111
|
+
├── cover.md # reader splash (optional)
|
|
112
|
+
├── _sidebar.md # reader navigation (optional)
|
|
113
|
+
├── _topbar.md # reader top bar (optional)
|
|
114
|
+
├── .pict_documentation_topics.json # topic manifest (optional)
|
|
115
|
+
├── guides/
|
|
116
|
+
│ ├── getting-started.md
|
|
117
|
+
│ └── images/
|
|
118
|
+
│ └── screenshot.png
|
|
119
|
+
└── api/
|
|
120
|
+
└── reference.md
|
|
40
121
|
```
|
|
41
122
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
## Editor Features
|
|
123
|
+
## Documentation
|
|
45
124
|
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
125
|
+
- [Overview](docs/README.md)
|
|
126
|
+
- [Quick Start](docs/quickstart.md)
|
|
127
|
+
- [Architecture](docs/architecture.md)
|
|
128
|
+
- [Configuration](docs/configuration.md)
|
|
129
|
+
- [API Reference](docs/api-reference.md)
|
|
130
|
+
- [Code Snippets](docs/code-snippets.md)
|
|
131
|
+
- [Persistence Hooks](docs/persistence-hooks.md) -- how to plug in custom markdown and image storage
|
|
132
|
+
- [CLI Reference](docs/cli-reference.md)
|
|
52
133
|
|
|
53
|
-
|
|
134
|
+
## Keyboard Shortcuts
|
|
54
135
|
|
|
55
136
|
| Shortcut | Action |
|
|
56
|
-
|
|
57
|
-
| `
|
|
58
|
-
| `Escape` | Close file (
|
|
59
|
-
| `F1` | Toggle
|
|
137
|
+
|---|---|
|
|
138
|
+
| `Ctrl+S` / `Cmd+S` | Save the current file |
|
|
139
|
+
| `Escape` | Close the current file (prompts if dirty) |
|
|
140
|
+
| `F1` | Toggle live preview |
|
|
60
141
|
| `F2` | Toggle sidebar |
|
|
61
|
-
| `F3`
|
|
62
|
-
| `F4`
|
|
142
|
+
| `F3` | Upload image at cursor |
|
|
143
|
+
| `F4` | Toggle settings panel |
|
|
63
144
|
|
|
64
|
-
##
|
|
65
|
-
|
|
66
|
-
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.
|
|
67
|
-
|
|
68
|
-
## Architecture
|
|
69
|
-
|
|
70
|
-
Built on these Retold modules:
|
|
71
|
-
|
|
72
|
-
- **[Orator](https://github.com/stevenvelozo/orator)** -- HTTP server with Restify
|
|
73
|
-
- **[Pict](https://github.com/stevenvelozo/pict)** -- MVC framework for the browser applications
|
|
74
|
-
- **[pict-docuserve](https://github.com/stevenvelozo/pict-docuserve)** -- Documentation reader/viewer
|
|
75
|
-
- **[pict-section-markdowneditor](https://github.com/stevenvelozo/pict-section-markdowneditor)** -- CodeMirror markdown editor component
|
|
76
|
-
- **[pict-section-code](https://github.com/stevenvelozo/pict-section-code)** -- CodeJar code editor component
|
|
77
|
-
- **[pict-section-filebrowser](https://github.com/stevenvelozo/pict-section-filebrowser)** -- File browser component
|
|
78
|
-
- **[pict-service-commandlineutility](https://github.com/stevenvelozo/pict-service-commandlineutility)** -- CLI framework
|
|
79
|
-
|
|
80
|
-
## Development
|
|
145
|
+
## Building
|
|
81
146
|
|
|
82
147
|
```bash
|
|
83
|
-
# Clone and install
|
|
84
|
-
git clone https://github.com/stevenvelozo/retold.git
|
|
85
|
-
cd retold/app/retold-content-system
|
|
86
|
-
npm install
|
|
87
|
-
|
|
88
|
-
# Build everything (CodeMirror bundle, CodeJar bundle, application bundle)
|
|
89
148
|
npm run build-all
|
|
90
|
-
|
|
91
|
-
# Start the dev server
|
|
92
|
-
npm start
|
|
93
149
|
```
|
|
94
150
|
|
|
95
|
-
|
|
151
|
+
Produces a browser bundle at `web-application/retold-content-system.min.js` plus the CodeMirror and CodeJar bundles.
|
|
96
152
|
|
|
97
|
-
##
|
|
98
|
-
|
|
99
|
-
Full documentation is in the `docs/` folder and can be viewed with the content system itself:
|
|
153
|
+
## Related Packages
|
|
100
154
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
155
|
+
- [pict](https://github.com/stevenvelozo/pict) -- MVC framework
|
|
156
|
+
- [pict-application](https://github.com/stevenvelozo/pict-application) -- application host and lifecycle
|
|
157
|
+
- [pict-docuserve](https://github.com/stevenvelozo/pict-docuserve) -- documentation reader used for the `/` route
|
|
158
|
+
- [pict-section-markdowneditor](https://github.com/stevenvelozo/pict-section-markdowneditor) -- CodeMirror-based markdown editor
|
|
159
|
+
- [pict-section-code](https://github.com/stevenvelozo/pict-section-code) -- CodeJar-based code editor
|
|
160
|
+
- [pict-section-filebrowser](https://github.com/stevenvelozo/pict-section-filebrowser) -- file browser sidebar
|
|
161
|
+
- [orator](https://github.com/stevenvelozo/orator) -- REST server framework
|
|
104
162
|
|
|
105
163
|
## License
|
|
106
164
|
|
|
107
165
|
MIT
|
|
166
|
+
|
|
167
|
+
## Contributing
|
|
168
|
+
|
|
169
|
+
Pull requests welcome. See the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md) for the code of conduct, contribution process, and testing requirements.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "retold-content-system",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.13",
|
|
4
4
|
"description": "Retold Content System - Markdown content viewer and editor",
|
|
5
5
|
"main": "source/Pict-ContentSystem-Bundle.js",
|
|
6
6
|
"bin": {
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"author": "steven velozo <steven@velozo.com>",
|
|
29
29
|
"license": "MIT",
|
|
30
30
|
"optionalDependencies": {
|
|
31
|
-
"ultravisor-beacon": "^0.0.
|
|
31
|
+
"ultravisor-beacon": "^0.0.2"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
34
|
"fable": "^3.1.66",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"orator-serviceserver-restify": "^2.0.9",
|
|
37
37
|
"pict": "^1.0.359",
|
|
38
38
|
"pict-application": "^1.0.33",
|
|
39
|
-
"pict-docuserve": "^0.
|
|
39
|
+
"pict-docuserve": "^0.1.1",
|
|
40
40
|
"pict-provider": "^1.0.12",
|
|
41
41
|
"pict-section-code": "^1.0.4",
|
|
42
42
|
"pict-section-content": "^0.0.11",
|
|
@@ -53,7 +53,7 @@
|
|
|
53
53
|
"codemirror": "^6.0.2",
|
|
54
54
|
"esbuild": "^0.27.4",
|
|
55
55
|
"highlight.js": "^11.11.1",
|
|
56
|
-
"quackage": "^1.0
|
|
56
|
+
"quackage": "^1.1.0"
|
|
57
57
|
},
|
|
58
58
|
"copyFilesSettings": {
|
|
59
59
|
"whenFileExists": "overwrite"
|
|
@@ -368,12 +368,16 @@ function setupContentSystemServer(pOptions, fCallback)
|
|
|
368
368
|
let tmpBuffer = Buffer.isBuffer(tmpBody) ? tmpBody : Buffer.from(tmpBody);
|
|
369
369
|
libFs.writeFileSync(tmpFilePath, tmpBuffer);
|
|
370
370
|
|
|
371
|
-
// Build the URL
|
|
371
|
+
// Build the URL. Use the bare filename so the markdown
|
|
372
|
+
// reference is relative to the document's own directory.
|
|
373
|
+
// This makes images portable — they work in the content
|
|
374
|
+
// system's live server (the preview resolver prepends
|
|
375
|
+
// the base path), on GitHub Pages, or any static host.
|
|
372
376
|
let tmpRelativePath = tmpRelativeFolder
|
|
373
377
|
? (tmpRelativeFolder + '/' + tmpUniqueFilename)
|
|
374
378
|
: tmpUniqueFilename;
|
|
375
|
-
let tmpURL =
|
|
376
|
-
tmpFable.log.info(`Image uploaded: ${tmpURL} (${tmpBuffer.length} bytes)`);
|
|
379
|
+
let tmpURL = tmpUniqueFilename;
|
|
380
|
+
tmpFable.log.info(`Image uploaded: ${tmpURL} -> ${tmpRelativePath} (${tmpBuffer.length} bytes)`);
|
|
377
381
|
|
|
378
382
|
pResponse.send(
|
|
379
383
|
{
|