From b60bf351175ddc96acad2a111077942d54f0bf5a Mon Sep 17 00:00:00 2001 From: matthewrgourd Date: Wed, 15 Apr 2026 17:24:16 +0100 Subject: [PATCH 1/2] docs(readme): add Ask AI preview CORS and backend dependency notes --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index afb38a3..1fc9833 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,22 @@ Each push to `main` triggers a new deployment. PRs get preview URLs automaticall - `VERCEL_TOKEN` - create at [vercel.com/account/tokens](https://vercel.com/account/tokens) - `VERCEL_PROJECT_ID` - from your Vercel project **Settings → General** (or from `.vercel/project.json` after `vercel link`) +### Ask AI backend and preview behavior + +The Ask AI panel in this repo calls `https://chat.devdocify.com/api/widget-chat` from the browser. + +For production and Vercel preview environments to work: + +- `chat-devdocify` must be deployed and healthy. +- The widget API CORS policy must allow: + - `https://www.devdocify.com` + - `https://devdocify.com` + - `http://localhost:*` + - `https://doc-platform*.vercel.app` preview origins + +If preview origins are not allowed by CORS, Ask AI requests fail in browser and the panel shows: +`Sorry, something went wrong. Please try again.` + ## Optional: self-hosted deployment For containerized or on-prem deployments, the repo includes Docker, nginx, and a monitoring stack. From 64e76fa8cd5a4f3becf6593dd2a312c2a0f9d674 Mon Sep 17 00:00:00 2001 From: matthewrgourd Date: Wed, 15 Apr 2026 17:57:49 +0100 Subject: [PATCH 2/2] docs(devdocify): tighten how-to/tutorial copy --- docs/devdocify/how-to/add-docset.md | 30 ++++++++--- docs/devdocify/how-to/add-playground.md | 43 ++++++++------- docs/devdocify/how-to/configure-search.md | 36 +++++++------ docs/devdocify/reference/index.md | 13 ++--- .../reference/navigation-contract.md | 22 ++++---- docs/devdocify/tutorials/quick-start.md | 53 ++++++++++--------- 6 files changed, 110 insertions(+), 87 deletions(-) diff --git a/docs/devdocify/how-to/add-docset.md b/docs/devdocify/how-to/add-docset.md index ee7240b..d420e36 100644 --- a/docs/devdocify/how-to/add-docset.md +++ b/docs/devdocify/how-to/add-docset.md @@ -9,6 +9,12 @@ description: "How to add a new product docset to a DevDocify site, including dir Follow these steps to add a new product docset to your DevDocify site. +## Prerequisites + +- You are in the project root. +- You can edit `docusaurus.config.ts`. +- You have the `docify` CLI installed. + ## 1. Create the docs directory Create a directory for your new product under `docs/`: @@ -17,13 +23,13 @@ Create a directory for your new product under `docs/`: mkdir -p docs/myproduct/getting-started ``` -Add a minimal index page: +Create a minimal index page: ```bash touch docs/myproduct/getting-started/index.md ``` -## 2. Add a navigation.json +## 2. Add `navigation.json` Create `docs/myproduct/navigation.json`. This file defines the sidebar for the docset: @@ -39,11 +45,11 @@ Create `docs/myproduct/navigation.json`. This file defines the sidebar for the d ] ``` -See the [Navigation contract](/docs/reference/navigation-contract) for the full schema and validation rules. +See the [Navigation contract](/docs/reference/navigation-contract) for the schema and validation rules. -## 3. Add the plugin to docusaurus.config.ts +## 3. Add the docs plugin in `docusaurus.config.ts` -Add a `@docusaurus/plugin-content-docs` entry inside the `plugins` array in `docusaurus.config.ts`: +Add a `@docusaurus/plugin-content-docs` entry inside the `plugins` array: ```ts [ @@ -86,13 +92,23 @@ In `docusaurus.config.ts`, add an entry to `themeConfig.navbar.items`: ## 6. Add a footer link (optional) -Add a link to `themeConfig.footer.links` in the appropriate column. +Add a link to `themeConfig.footer.links` in the relevant column. ## 7. Validate -Run validation to check that your navigation contract is valid and the build succeeds: +Run validation to confirm your navigation contract is valid and the site builds: ```bash docify validate docify build ``` + +## 8. Verify in the browser + +Run the dev server and verify the new docset route and sidebar: + +```bash +docify dev +``` + +Open `http://localhost:3000/myproduct/getting-started` and confirm the sidebar loads your `navigation.json` entries. diff --git a/docs/devdocify/how-to/add-playground.md b/docs/devdocify/how-to/add-playground.md index 47831f2..325aca9 100644 --- a/docs/devdocify/how-to/add-playground.md +++ b/docs/devdocify/how-to/add-playground.md @@ -11,9 +11,9 @@ Follow these steps to add an interactive API playground to a DevDocify docset. ## Before you start -You'll need: +You need: -- An OpenAPI description file (JSON or YAML) for your API +- An OpenAPI description file (`.json` or `.yaml`) - An existing docset directory under `docs/` - Write access to `docusaurus.config.ts` @@ -21,23 +21,23 @@ You'll need: Place your OpenAPI file in the `openapi/` directory at the project root: -``` +```text openapi/my-api.json ``` -Keep the spec scoped to the operations you want to expose in the playground. Curated three-to-five operation specs work better than full API surface dumps for onboarding purposes. +Keep the spec scoped to the operations you want to expose in the playground. ## 2. Install the OpenAPI plugin -Install the plugin if it's not already present: +Install the plugin if it isn't already present: ```bash npm install docusaurus-plugin-openapi-docs @docusaurus/plugin-content-docs ``` -## 3. Configure the plugin in docusaurus.config.ts +## 3. Configure the plugin in `docusaurus.config.ts` -Add a plugin entry for your docset: +Add a plugin entry: ```ts [ @@ -60,38 +60,45 @@ Add a plugin entry for your docset: ## 4. Create the playground page -Add a playground page to your docset. A minimal page needs: - -- A route under your docset base path (for example `/my-product/api-playground`) -- A React component that renders the interactive explorer +Add a page under your docset base path, for example `/my-product/api-playground`, that renders the interactive explorer. -Use the TfL or Petstore playground pages as reference implementations: +Use these pages as reference implementations: - `src/pages/tfl/api-playground.tsx` - `src/pages/petstore/api-playground.tsx` -## 5. Add a playground guide to your docset +## 5. Add a playground guide in your docset -Create a `getting-started/playground.md` file in your docset directory that explains: +Create `getting-started/playground.md` in your docset and explain: 1. What the playground demonstrates -2. Scope and limits (number of operations, auth requirements) +2. Scope and limits (operations, auth requirements) 3. Try-it defaults and why you chose them 4. Expected response behavior 5. Where to go next -Add the file to your docset's `navigation.json` inside the Getting started category. +Add this file to your docset `navigation.json` under your Getting started category. ## 6. Validate -Run the following to confirm the build succeeds: +Run: ```bash docify build ``` -Or check for broken links specifically: +If you only want to check link integrity: ```bash docify broken-links ``` + +## 7. Verify behavior + +Start local dev and test at least one request in the playground UI: + +```bash +docify dev +``` + +Confirm the route loads and the sample requests return expected responses. diff --git a/docs/devdocify/how-to/configure-search.md b/docs/devdocify/how-to/configure-search.md index 7ad87ee..f9f7c09 100644 --- a/docs/devdocify/how-to/configure-search.md +++ b/docs/devdocify/how-to/configure-search.md @@ -7,23 +7,29 @@ description: "How to configure Algolia DocSearch for a DevDocify site, including # Configure search -DevDocify uses Algolia DocSearch for full-text search across all docsets. Follow these steps to configure it. +DevDocify uses Algolia DocSearch for full-text search across docsets. + +## Prerequisites + +- A deployed docs URL that Algolia can crawl +- Access to your `docusaurus.config.ts` +- Access to Algolia DocSearch or Algolia dashboard ## 1. Apply for DocSearch -Go to [docsearch.algolia.com](https://docsearch.algolia.com) and apply with your site's URL. +Go to [docsearch.algolia.com](https://docsearch.algolia.com) and apply with your site URL. -Algolia reviews applications for documentation sites manually. Approval typically takes a few days. You'll receive an email with your `appId`, `apiKey`, and `indexName` when approved. +After approval, Algolia sends your `appId`, `apiKey`, and `indexName`. -If you need immediate access, create an Algolia account directly at [algolia.com](https://www.algolia.com) and set up a free application. +If you need immediate access, create an Algolia app directly at [algolia.com](https://www.algolia.com). ## 2. Run a test crawl -Once your Algolia application is provisioned, run a manual crawl from the Algolia Crawler dashboard to confirm the index populates correctly before wiring it into the site. +Run a manual crawl from the Algolia Crawler dashboard and verify records are indexed before wiring search into the site. -## 3. Add the credentials to docusaurus.config.ts +## 3. Add credentials in `docusaurus.config.ts` -In `docusaurus.config.ts`, add an `algolia` block inside `themeConfig`: +Add an `algolia` block inside `themeConfig`: ```ts themeConfig: { @@ -36,26 +42,24 @@ themeConfig: { }, ``` -Do not commit your write API key. The `apiKey` here is the public **search-only** key. It's safe to include in source. +Use a public search-only key here. Do not commit write/admin API keys. ## 4. Enable contextual search -For multi-docset sites, `contextualSearch: true` scopes search results to the current docset. Algolia uses the Docusaurus `docusaurus_tag` facet to filter results. +For multi-docset sites, `contextualSearch: true` scopes results to the current docset. -If your index doesn't include the tag facet, update your Algolia crawler configuration to include it. The Docusaurus documentation has an [example crawler config](https://docusaurus.io/docs/search#using-algolia-docsearch) you can adapt. +If your index doesn't include the Docusaurus facet tags, update your crawler config to include `docusaurus_tag` in `attributesForFaceting`. ## 5. Test locally -Start the dev server: - ```bash docify dev ``` -Use the search box to confirm results are scoped correctly to the active docset. +Use the search box in at least two docsets to confirm scoped results. ## Troubleshooting -- **No results**: Check that your Algolia index has been crawled and contains documents. Run a manual crawl from the Algolia dashboard. -- **Results from other docsets showing up**: Confirm `contextualSearch: true` is set and the crawler config includes `docusaurus_tag` in the `attributesForFaceting` list. -- **Search box not appearing**: Confirm your `themeConfig.algolia` block is inside the correct preset config and not duplicated. +- No results: verify crawl success and index contents in Algolia. +- Cross-docset results: confirm `contextualSearch: true` and `docusaurus_tag` faceting. +- Search box missing: verify `themeConfig.algolia` is present once in the active config. diff --git a/docs/devdocify/reference/index.md b/docs/devdocify/reference/index.md index a10c679..9991e3b 100644 --- a/docs/devdocify/reference/index.md +++ b/docs/devdocify/reference/index.md @@ -2,7 +2,7 @@ sidebar_position: 1 slug: /reference title: Reference -description: "Technical reference for DevDocify. CLI commands, navigation contract schema, route model, and configuration entry points." +description: "Technical reference for DevDocify: CLI commands, navigation contract schema, route model, and configuration entry points." --- # Reference @@ -16,9 +16,7 @@ Use reference pages when you need exact facts, supported options, and stable tec

-## CLI reference - -See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, and examples. +## Reference pages
CLI reference @@ -29,7 +27,7 @@ See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, a

/ marketing-first root surface

-

/docs first-party technical product docs (Diátaxis)

+

/docs first-party technical product docs (Diataxis)

/tfl demo TfL product docs

/petstore demo Petstore product docs

/tfl/api-playground and /petstore/api-playground interactive demo routes

@@ -40,8 +38,5 @@ See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, a - Site config: `docusaurus.config.ts` - Sidebars: `sidebarsDevDocify.ts`, `sidebarsTfl.ts`, `sidebarsPetstore.ts` - Navigation contract loader: `navigation-contract.ts` -- Navigation definitions: - - `docs/devdocify/navigation.json` - - `docs/tfl/navigation.json` - - `docs/petstore/navigation.json` +- Navigation definitions: `docs/*/navigation.json` - Workflows: `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`, `.github/workflows/preview.yml` diff --git a/docs/devdocify/reference/navigation-contract.md b/docs/devdocify/reference/navigation-contract.md index b1b799b..b5e6c0e 100644 --- a/docs/devdocify/reference/navigation-contract.md +++ b/docs/devdocify/reference/navigation-contract.md @@ -16,7 +16,7 @@ These files are loaded and validated by `navigation-contract.ts` and then consum ## Supported node types -Each node must declare a `type`: +Each node must declare `type`: - `doc`: `{"type":"doc","id":"path/to/doc","label":"Optional label"}` - `category`: `{"type":"category","label":"Section","items":[...]}` @@ -26,20 +26,20 @@ Each node must declare a `type`: Validation runs at build/start time and fails fast when the contract is invalid. -Examples of invalid input that fail the build with actionable errors: +Examples that fail validation: -- root is not an array -- missing or unsupported `type` -- `doc` node without `id` -- `link` node without `href` -- `category` node without non-empty `items` +- Root isn't an array. +- Missing or unsupported `type`. +- `doc` node without `id`. +- `link` node without `href`. +- `category` node without non-empty `items`. ## Deep nesting support -The contract parser is recursive and supports deeply nested category trees, including trees deeper than five levels. +The parser is recursive and supports deeply nested category trees. ## Why this model -- one navigation file per docset/version -- deterministic, validated behavior before publish -- easier ownership and change review for information architecture updates +- One navigation file per docset or version. +- Deterministic behavior before publish. +- Easier ownership and review for information architecture changes. diff --git a/docs/devdocify/tutorials/quick-start.md b/docs/devdocify/tutorials/quick-start.md index 6ee5227..407a393 100644 --- a/docs/devdocify/tutorials/quick-start.md +++ b/docs/devdocify/tutorials/quick-start.md @@ -11,18 +11,17 @@ This tutorial walks you from installing the CLI to deploying a DevDocify site. I ## What you'll build -A new documentation site running locally, with content validation and broken-link checks passing, ready to push to Vercel. +A new documentation site running locally, with content validation and broken-link checks passing, ready to deploy to Vercel. ## Prerequisites -- Node.js 20.17.0 or later -- An npm account (for global install) -- A GitHub account (for the deploy step) -- A Vercel account (for the deploy step) +- Node.js 20.17.0 or later (includes npm) +- A GitHub account (for deployment) +- A Vercel account (for deployment) --- -## Step 1 — Install the CLI +## Step 1: Install the CLI Install the Docify CLI globally: @@ -30,7 +29,7 @@ Install the Docify CLI globally: npm install -g @devdocify/cli ``` -Confirm it's working: +Confirm it's available: ```bash docify --version @@ -38,7 +37,7 @@ docify --version --- -## Step 2 — Create a project +## Step 2: Create a project Scaffold a new DevDocify project in a directory called `my-docs`: @@ -46,8 +45,6 @@ Scaffold a new DevDocify project in a directory called `my-docs`: docify new my-docs ``` -The CLI creates the directory with a minimal Docusaurus project, a placeholder doc, and a `.gitignore`. - Change into the new directory and install dependencies: ```bash @@ -57,7 +54,7 @@ npm install --- -## Step 3 — Start the dev server +## Step 3: Start the dev server ```bash docify dev @@ -65,13 +62,13 @@ docify dev Open [http://localhost:3000](http://localhost:3000) in your browser. You should see your new docs site. -Edit `docs/index.md` and save — the browser reloads automatically. +Edit `docs/index.md` and save. The browser should reload automatically. -Press `Ctrl+C` to stop the dev server when you're done. +Press `Ctrl+C` to stop the dev server when you are done. --- -## Step 4 — Validate content +## Step 4: Validate content Run the content linter to catch common issues before you build: @@ -79,7 +76,7 @@ Run the content linter to catch common issues before you build: docify validate ``` -If your project's `package.json` doesn't have a `lint-content` script yet, add one: +If your `package.json` doesn't have a `lint-content` script yet, add one: ```json "lint-content": "echo \"No linter configured\"" @@ -87,7 +84,7 @@ If your project's `package.json` doesn't have a `lint-content` script yet, add o --- -## Step 5 — Check for broken links +## Step 5: Check for broken links Build the site and check every internal link: @@ -99,7 +96,7 @@ Fix any broken links reported before continuing. --- -## Step 6 — Build and deploy +## Step 6: Build and deploy Build a production bundle: @@ -107,15 +104,19 @@ Build a production bundle: docify build ``` -To deploy to Vercel: +Deploy to Vercel: 1. Push your project to a GitHub repository. 2. Log in to [vercel.com](https://vercel.com) and click **Add New Project**. 3. Import your GitHub repository. -4. Set the following in the Vercel project settings: - - **Build command**: `npm run build` - - **Output directory**: `build` - - **Install command**: `npm install` +4. Set the following in Vercel project settings: + +| Setting | Value | +|---|---| +| Build command | `npm run build` | +| Output directory | `build` | +| Install command | `npm install` | + 5. Click **Deploy**. Vercel runs a build on every push to `main` and creates preview deployments for every pull request. @@ -124,7 +125,7 @@ Vercel runs a build on every push to `main` and creates preview deployments for ## What's next -- [Add a docset](/docs/how-to/add-docset) — bring a new product into your site -- [Add an API playground](/docs/how-to/add-playground) — add an interactive OpenAPI explorer -- [Configure search](/docs/how-to/configure-search) — set up Algolia DocSearch -- [CLI reference](/docs/reference/cli) — all commands and flags +- [Add a docset](/docs/how-to/add-docset) +- [Add an API playground](/docs/how-to/add-playground) +- [Configure search](/docs/how-to/configure-search) +- [CLI reference](/docs/reference/cli)