diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..44664a12 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md + +Review `README.md` and `CONTRIBUTING.md` for all relevant repository information. + +## Development Tips + +- Use `npm install` to install dependencies. +- Use `npm run dev` to start the local development server (runs `prebuild` automatically). +- Use `npm run build` to produce a production build (also runs `prebuild` automatically). +- Do not edit files in `build/`; it is compiled output. +- The `scripts/prebuild.js` script must run before the dev server or build — it is wired into `predev`/`prebuild` hooks, so calling `npm run dev` or `npm run build` is sufficient. + +## Code Style + +- TypeScript (config files and scripts), MDX/Markdown (content). +- Prettier is configured via `@harperdb/code-guidelines/prettier` (see `package.json`). +- Format command: `npm run format:write`. Run this after editing any `.ts`, `.md`, or `.mdx` files. +- The lint script is a no-op (`echo 0`); do not expect `npm run lint` to catch issues. + +## Content Structure + +- Content lives in four directories: `learn/`, `reference/`, `release-notes/`, and `fabric/`. +- Sidebar configs: `sidebarsLearn.ts`, `sidebarsReference.ts`, `sidebarsReleaseNotes.ts`, `sidebarsFabric.ts`. +- Reference is versioned; current version is v5 (`reference/`). Archived v4 content is in `reference_versioned_docs/version-v4/`. +- Do not modify `reference_versioned_docs/` for current (v5) work; edit `reference/` instead. +- The `` component is globally registered — no import needed in `.md`/`.mdx` files. +- See the complete repository organization in `CONTRIBUTING.md` + +## Testing + +- There is no automated test suite. Verification is done by running the dev server or build. +- `npm run build` is the best end-to-end check — it will fail on broken links, missing imports, or MDX errors. +- `npm run typecheck` checks TypeScript config files only. +- Known issue: `npm run serve` (post-build preview) 404s on paths like `/docs/4.X` locally due to an upstream `serve-handler` bug. This is not a real breakage — see CONTRIBUTING.md for details. + +## CI + +- CI runs `npm run build` and `npm run format:check` on pull requests. +- If CI fails on formatting, run `npm run format:write` locally and commit the result. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cf38f0c..4be87a17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,13 +70,7 @@ Learn is non-versioned. All content lives directly in `learn/` organized into ca | 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 -``` +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 _current_ major). #### Release Notes @@ -86,7 +80,7 @@ node scripts/cut-version.js | 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. +Release notes are non-versioned in the Docusaurus sense — major version organization is handled manually via subdirectories (`v5-lincoln/`, `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 @@ -135,7 +129,7 @@ Reference sidebar headers use `className: "reference-category-header"` for compa #### 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. +Deprecated or discouraged features belong in `reference/legacy/`. Each legacy page should briefly explain what the feature was and direct users to the modern alternative. --- @@ -184,20 +178,28 @@ In previous versions of v4, the default was 9925. SQL is still supported but discouraged. See [Database](../database/overview.md) for modern alternatives. ``` -**Configuration option** (inline in a list): +**Stabilized feature:** ```mdx -- `logger.level` — Log level; _Default_: `"info"` (Added in: v4.1.0) -``` +## Plugin API -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 `` for standalone placement after headings. +{/* Now stable! */} -If the introduction version is inferred rather than confirmed by release notes, append a note: + +{/* Was "experimental" */} + + +The Plugin API is the primary way to implement additional functionality in Harper. +``` + +**Configuration option** (inline in a list): ```mdx - (inferred from version comparison, needs verification) +- `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 `` for standalone placement after headings. + ## Known Issues ### `docusaurus serve` 404s on `/docs/4.X` paths diff --git a/README.md b/README.md index c400f503..7666ab41 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Documentation website for [Harper](https://harper.fast), a fullstack, serverful Node.js application platform. -Powered by [Docusaurus](https://docusaurus.io/). +Hosted at [docs.harper.fast](https://docs.harper.fast). Powered by [Docusaurus](https://docusaurus.io/). ## Contributing diff --git a/scripts/cut-version.js b/scripts/cut-version.js deleted file mode 100644 index 782b1858..00000000 --- a/scripts/cut-version.js +++ /dev/null @@ -1,116 +0,0 @@ -#!/usr/bin/env node - -/** - * Script to cut a new version from the repository's /docs directory - * This is used for creating new versions (4.7+) after the GitBook migration - * - * Usage: npm run version - * Example: npm run version 4.7 - */ - -const fs = require('node:fs'); -const path = require('node:path'); -const { execSync } = require('node:child_process'); - -const SCRIPT_DIR = __dirname; -const SITE_DIR = path.dirname(SCRIPT_DIR); -const REPO_ROOT = path.dirname(SITE_DIR); -const REPO_DOCS = path.join(REPO_ROOT, 'docs'); -const SITE_DOCS = path.join(SITE_DIR, 'docs'); - -function copyDirectory(src, dest) { - // Create destination directory - fs.mkdirSync(dest, { recursive: true }); - - // Read all items in source directory - const items = fs.readdirSync(src, { withFileTypes: true }); - - for (const item of items) { - const srcPath = path.join(src, item.name); - const destPath = path.join(dest, item.name); - - if (item.isDirectory()) { - // Recursively copy subdirectories - copyDirectory(srcPath, destPath); - } else { - // Copy file - fs.copyFileSync(srcPath, destPath); - } - } -} - -function removeDirectory(dir) { - if (fs.existsSync(dir)) { - fs.rmSync(dir, { recursive: true, force: true }); - } -} - -function main() { - const version = process.argv[2]; - - if (!version) { - console.error('Usage: npm run version '); - console.error('Example: npm run version 4.7'); - process.exit(1); - } - - // Validate version format - if (!/^\d+\.\d+$/.test(version)) { - console.error(`Error: Invalid version format "${version}". Expected format: X.Y (e.g., 4.7)`); - process.exit(1); - } - - console.log(`\nCutting version ${version} from repository docs...`); - - // Check if repo docs exist - if (!fs.existsSync(REPO_DOCS)) { - console.error(`Error: Repository docs not found at ${REPO_DOCS}`); - console.error('After migration, the repository /docs directory should contain vNext documentation.'); - process.exit(1); - } - - // Remove existing site/docs if it exists (it's just a build-time copy) - if (fs.existsSync(SITE_DOCS)) { - console.log('Removing existing site/docs (build-time copy)...'); - removeDirectory(SITE_DOCS); - } - - try { - // Copy repo docs to site docs - console.log('Copying repository docs to site/docs...'); - copyDirectory(REPO_DOCS, SITE_DOCS); - - // Run Docusaurus version command - console.log(`\nRunning Docusaurus version command for ${version}...`); - execSync(`npm run docusaurus docs:version ${version}`, { - cwd: SITE_DIR, - stdio: 'inherit', - }); - - console.log(`\n✅ Successfully created version ${version}`); - console.log(` - Versioned docs created at: versioned_docs/version-${version}/`); - console.log(` - Version added to versions.json`); - - // Clean up - remove the temporary site/docs (it's in .gitignore anyway) - console.log('\nCleaning up temporary site/docs...'); - removeDirectory(SITE_DOCS); - - console.log('\n🎉 Version creation complete!'); - console.log('\nNext steps:'); - console.log('1. Create a PR with the new versioned docs and updated versions.json'); - console.log('2. Site will deploy automatically when PR is merged'); - console.log(`\nNote: Version ${version} is now the latest and will be synced to site/docs during build`); - } catch (error) { - console.error('\n❌ Error creating version:', error.message || error); - - // Clean up on error - if (fs.existsSync(SITE_DOCS)) { - console.log('Cleaning up temporary site/docs...'); - removeDirectory(SITE_DOCS); - } - - process.exit(1); - } -} - -main();