retold 1.0.6 → 4.0.2

package/docs/retold-building-documentation.md

@@ -0,0 +1,33 @@
+# Building and Maintaining the Retold Documentation
+
+The Retold documentation is powered by [pict-docuserve](https://github.com/stevenvelozo/pict-docuserve), a single-page documentation viewer built on the Pict MVC framework. The catalog and keyword search index are generated by [indoctrinate](https://github.com/stevenvelozo/indoctrinate).
+
+## Serving Locally
+
+```shell
+npm run serve-docs
+```
+
+This starts a local HTTP server at `http://127.0.0.1:3333`.
+
+## Rebuilding the Catalog and Search Index
+
+When the module structure changes (a new module is added, a sidebar is reorganized, etc.):
+
+```shell
+npm run build-docs
+```
+
+This runs `npx quack prepare-docs ./docs -d ./modules` which:
+
+1. Generates `retold-catalog.json` from the module directory tree
+2. Generates `retold-keyword-index.json` with a Lunr full-text search index
+3. Injects pict-docuserve assets (index.html, JS bundle, CSS) into `docs/`
+
+Commit the updated files to the repository.
+
+## Individual Package Content has Changed
+
+When the content of an individual package changes (a markdown file is edited, a new doc is added, etc.) there is nothing to do for the live site. Module documentation is fetched from `raw.githubusercontent.com` as the user navigates.
+
+To update the search index to include new content, re-run `npm run build-docs`.