Docs -> Reference (Major version consolidation) Base

.github/workflows/pr-preview.yaml

@@ -5,6 +5,10 @@ on:
     types: [opened, synchronize, reopened, closed]
     # Temporarily disable the file filter so we get preview deploys for reference docs migration PRs
     # paths:
+    #   - 'reference/**'
+    #   - 'reference_versioned_docs/**'
+    #.  - 'reference_versioned_sidebars/**'
+    #   - 'reference_versions.json'
     #   - 'docs/**'
     #   - 'fabric/**'
     #   - 'learn/**'

CONTRIBUTING.md

@@ -25,24 +25,203 @@ npm run dev
 4. Format your code:
 
 ```bash
-npm run format
+npm run format:write
 ```
 
 5. Push changes to a branch and create a pull request
 
 ## Site Organization
 
-This site is powered by Docusaurus and leverages the file-system based versioning capabilities of the framework.
+This site is powered by Docusaurus. The documentation is split into four distinct sections, each serving a different purpose and configured as its own Docusaurus plugin instance.
 
-There are two directories where actual documentation content lives.
+### The Four Sections
 
-The first, `docs/` contains the "latest" or "next" version of the documentation. We do not publish or render this directory, and the content here is meant to represent on-going development.
+| Section           | URL              | Purpose                                                                                                                      |
+| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **Learn**         | `/learn`         | Guides, tutorials, and conceptual introductions. How-to content that walks users through a goal.                             |
+| **Reference**     | `/reference/vN`  | Complete technical reference for every feature, API, configuration option, and operation. Versioned by major Harper version. |
+| **Release Notes** | `/release-notes` | Changelog for every Harper release. Organized by major version codename (e.g. `v4-tucker`).                                  |
+| **Fabric**        | `/fabric`        | Documentation for Harper's managed cloud platform. Separate from the core Harper product docs.                               |
 
-The second, `versioned_docs` contains all of the specific Harper version documentation organized by minor version. The latest version within this directory maps to the default path on the site. For example, if the latest version is `versioned_docs/version-4.6/` then the page https://docs.harperdb.io/docs/getting-started/first-harper-app maps to the file `site/versioned_docs/version-4.6/getting-started/first-harper-app.md`. And for the previous 4.5 version the page http://localhost:3000/docs/4.5/getting-started/first-harper-app can be found at `site/versioned_docs/version-4.5/getting-started/first-harper-app.md`.
+**Rule of thumb**: if it explains _how something works_ or _what something does_, it belongs in Reference. If it explains _how to accomplish something_, it belongs in Learn. New feature documentation always goes in Reference first; Learn guides can link to it.
 
-Depending on the specific change, you may need to make updates to similar files across multiple version directories as well as the root `docs/`.
+### Section Configuration Map
 
-The site organization is ever evolving so make sure to revisit this file over time to stay up to date with the latest structure.
+Each section maps to specific source directories and config files:
+
+#### Learn
+
+| Item          | Location                                   |
+| ------------- | ------------------------------------------ |
+| Content       | `learn/`                                   |
+| Sidebar       | `sidebarsLearn.ts`                         |
+| Plugin config | `docusaurus.config.ts` → plugin id `learn` |
+
+Learn is non-versioned. All content lives directly in `learn/` organized into categories that match the sidebar.
+
+#### Reference
+
+| Item                  | Location                                                |
+| --------------------- | ------------------------------------------------------- |
+| Current (v5) content  | `reference/`                                            |
+| Archived (v4) content | `reference_versioned_docs/version-v4/`                  |
+| Current sidebar       | `sidebarsReference.ts`                                  |
+| v4 sidebar            | `reference_versioned_sidebars/version-v4-sidebars.json` |
+| Version list          | `reference_versions.json`                               |
+| Plugin config         | `docusaurus.config.ts` → plugin id `reference`          |
+
+Reference is versioned by major Harper version. The `reference_versions.json` file lists all archived versions — currently `["current", "v4"]`. The `current` version maps to `v5` (the in-progress next major) and is not published; `v4` is the default displayed version.
+
+To cut a new version snapshot (e.g. when v5 ships), run:
+
+```bash
+node scripts/cut-version.js
+```
+
+#### Release Notes
+
+| Item          | Location                                           |
+| ------------- | -------------------------------------------------- |
+| Content       | `release-notes/`                                   |
+| Sidebar       | `sidebarsReleaseNotes.ts`                          |
+| Plugin config | `docusaurus.config.ts` → plugin id `release-notes` |
+
+Release notes are non-versioned in the Docusaurus sense — major version organization is handled manually via subdirectories (`v4-tucker/`, `v3-monkey/`, etc.). The sidebar uses `autogenerated` directives so new files are picked up automatically. See the [Release Notes Process](#release-notes-process) section for the full workflow.
+
+#### Fabric
+
+| Item          | Location                                    |
+| ------------- | ------------------------------------------- |
+| Content       | `fabric/`                                   |
+| Sidebar       | `sidebarsFabric.ts`                         |
+| Plugin config | `docusaurus.config.ts` → plugin id `fabric` |
+
+Fabric is non-versioned. It documents the managed cloud platform independently of the Harper core product.
+
+---
+
+### Reference Section Structure
+
+The Reference section is organized as a flat list of feature-based sections — no deep nesting. Each top-level section corresponds to one Harper feature or subsystem.
+
+#### Section Layout
+
+Every section follows this pattern:
+
+```
+reference/
+└── {feature}/
+    ├── overview.md        # General introduction, architecture, concepts
+    ├── configuration.md   # Config options specific to this feature (if applicable)
+    ├── api.md             # JS/programmatic API reference (if applicable)
+    └── operations.md      # Operations API operations for this feature (if applicable)
+```
+
+Not every section needs all four files — some features only warrant an `overview.md`. The filenames above are conventions, not requirements.
+
+#### Section Order
+
+Sections are ordered in the sidebar by who needs them first:
+
+1. **Data & Application** — Database, Resources, Components
+2. **Access & Security** — REST, HTTP, Security, Users & Roles
+3. **Setup & Operation** — CLI, Configuration, Operations API
+4. **Features** — Logging, Analytics, MQTT, Static Files, Environment Variables, Replication, GraphQL Querying, Studio, Fastify Routes
+5. **Legacy** — Deprecated or discouraged features
+
+#### Sidebar Headers
+
+Reference sidebar headers use `className: "reference-category-header"` for compact styling. This is set on each category entry in the sidebar config. Do not use `learn-category-header` in reference sidebars.
+
+#### Legacy Section
+
+Deprecated or discouraged features belong in `reference/legacy/` (current) or `reference_versioned_docs/version-v4/legacy/` (v4). Each legacy page should briefly explain what the feature was and direct users to the modern alternative.
+
+---
+
+### Version Annotations
+
+Because the Reference section consolidates all minor versions of a major into one document, features are annotated inline to indicate when they were introduced or changed.
+
+Use the `<VersionBadge>` component. It is registered globally and requires no import in `.md` or `.mdx` files.
+
+```mdx
+<VersionBadge version="v4.3.0" />
+<VersionBadge type="changed" version="v4.5.0" />
+<VersionBadge type="deprecated" version="v4.2.0" />
+```
+
+The `type` prop defaults to `"added"`, so the most common case is just `version`. Place the badge on its own line directly below the heading it describes:
+
+**New feature:**
+
+```mdx
+## Relationships
+
+<VersionBadge version="v4.3.0" />
+
+The `@relation` directive allows you to define relationships between tables...
+```
+
+**Changed behavior:**
+
+```mdx
+### Default Port
+
+<VersionBadge type="changed" version="v4.5.0" />
+
+The default MQTT port changed from 9925 to 9933.
+In previous versions of v4, the default was 9925.
+```
+
+**Deprecated feature:**
+
+```mdx
+## SQL Querying
+
+<VersionBadge type="deprecated" version="v4.2.0" />
+
+SQL is still supported but discouraged. See [Database](../database/overview.md) for modern alternatives.
+```
+
+**Configuration option** (inline in a list):
+
+```mdx
+- `logger.level` — Log level; _Default_: `"info"` (Added in: v4.1.0)
+```
+
+For inline config option annotations inside list items, plain text `(Added in: vX.Y.Z)` is fine — using the component mid-sentence is awkward. Reserve `<VersionBadge>` for standalone placement after headings.
+
+If the introduction version is inferred rather than confirmed by release notes, append a note:
+
+```mdx
+<VersionBadge version="v4.3.0" /> (inferred from version comparison, needs verification)
+```
+
+## Known Issues
+
+### `docusaurus serve` 404s on `/docs/4.X` paths
+
+`docusaurus serve` uses `serve-handler`, which treats ending URL path segments containing a singular dot (e.g. `4.6`) as file extensions rather than directory names. This causes `/docs/4.6` to 404 locally even though the redirect page exists at `build/docs/4.6/index.html`. This doesn't apply to nested paths such as `/docs/4.6/developers`.
+
+A fix has been submitted upstream at https://github.com/vercel/serve-handler/pull/230. Once it merges and Docusaurus upgrades its dependency, the local patch can be removed.
+
+In the meantime, if you need to test these redirects locally, apply a change in `node_modules/serve-handler/src/index.js` around line 608 where you clear the `stats` variable from `lstat` if it is a directory so it falls through to the nested `index.html`.
+
+```js
+if (path.extname(relativePath) !== '') {
+	try {
+		stats = await handlers.lstat(absolutePath);
+		if (stats && stats.isDirectory()) {
+			stats = null;
+		}
+	} catch (err) {
+		if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') {
+			return internalError(absolutePath, response, acceptsJSON, current, handlers, config, err);
+		}
+	}
+}
+```
 
 ## Release Notes Process
 

README.md

@@ -1,6 +1,6 @@
 # Harper Documentation
 
-Documentation website for [Harper](https://harpersystems.dev), a fullstack, serverful Node.js application platform.
+Documentation website for [Harper](https://harper.fast), a fullstack, serverful Node.js application platform.
 
 Powered by [Docusaurus](https://docusaurus.io/).
 
@@ -11,82 +11,3 @@ This documentation site is open source!
 If you notice something out-of-place or have suggestions for improvement, please feel free to submit an issue and/or a pull request. Make sure to follow the relevant bug report and content/feature request templates.
 
 For more information on contributing, follow the [contribution guide](CONTRIBUTING.md).
-
-## 🚀 Quick Start
-
-```bash
-# Install dependencies
-npm install
-
-# Start development server
-npm start
-# Opens at http://localhost:3000
-
-# Build for production
-npm run build
-
-# Serve production build locally
-npm run serve
-```
-
-## 📁 Directory Structure
-
-```text
-├── docs/                # Main documentation content
-├── static/              # Static assets
-│   ├── img/             # Site images and logos (versioned)
-│   └── js/              # JavaScript files
-├── src/                 # React components and custom pages
-│   ├── css/             # Custom styles
-│   └── pages/           # Custom pages
-├── versioned_docs/      # Documentation for previous versions
-├── versioned_sidebars/  # Sidebar configurations for versions
-├── docusaurus.config.ts # Main Docusaurus configuration
-├── sidebars.ts          # Sidebar navigation structure
-├── redirects.ts         # URL redirects configuration
-└── versions.json        # Version configuration
-```
-
-## 🛠️ Development
-
-### Running Locally
-
-```bash
-# Start the development server with hot reload
-npm start
-
-# Clear cache if you encounter issues
-npm run clear
-```
-
-The development server runs at `http://localhost:3000` and automatically reloads when you make changes.
-
-### Other Commands
-
-```bash
-# Type checking
-npm run typecheck
-
-# Format code
-npm run format
-
-# Clean all generated files and caches
-npm run clear
-```
-
-## 📋 Cutting a New Version
-
-When releasing a new version of Harper documentation:
-
-```bash
-# Cut a new version (e.g., 4.7)
-npm run version
-```
-
-This will:
-
-1. Copy current docs to versioned_docs/version-4.7
-2. Copy current sidebars to versioned_sidebars
-3. Update versions.json
-
-After cutting a version, update `docusaurus.config.ts` to set the new `lastVersion`.