docugate 0.1.1 → 0.1.3

package/README.md

@@ -1,17 +1,45 @@
 # docugate
 
 Command-line tools for [DocuGate](https://www.trydocugate.site), which publishes
-documentation straight from the markdown in your GitHub repository and decides
+documentation straight from the markdown in your GitHub repositories and decides
 who may read it.
 
 ```sh
-npx docugate init     # set this repository up for DocuGate
-npx docugate check    # check the docs the way DocuGate will read them
-npx docugate openapi  # prepare an OpenAPI spec for the API reference
+npm i -g docugate
 ```
 
-Works with npm, pnpm, yarn and bun. Requires Node 18.17 or later. Run every
-command from the root of your repository.
+```sh
+docugate init     # set this repository up for DocuGate
+docugate check    # check the docs the way DocuGate will read them
+docugate openapi  # prepare an OpenAPI spec for the API reference
+```
+
+Installing the command once is usually simpler than reaching for a package
+manager in each repository: it needs no `package.json`, so it works just as
+well in a Go, Python or Flutter repository as in a JavaScript one. That matters
+because one DocuGate space can read from several repositories, and they are
+rarely all the same language.
+
+If you would rather not install it globally, `npm i -D docugate` adds it to a
+single Node project, which also pins the version for CI; `npx docugate` runs it
+without installing anything. Both work with pnpm, yarn and bun too.
+
+Requires Node 18.17 or later. Run every command from the root of your
+repository.
+
+## Several repositories in one space
+
+A space can merge the docs from a frontend, a backend and a mobile app into one
+set of pages, so a feature that spans all three is documented once instead of
+three times. Repositories are added to a space from its settings on
+[trydocugate.site](https://www.trydocugate.site/dashboard), not from here.
+
+What that changes for this package: run `init` and `check` in **each**
+repository that contributes docs. Every one gets its own `docugate.json`, naming
+its own docs folder. `check` reads the repository it is run in, which is why its
+300-page limit is per repository rather than per space.
+
+See [Merging repositories](https://www.trydocugate.site/docs/merging-repositories).
 
 ## `init`
 
@@ -20,7 +48,7 @@ Creates a `docugate.json` and, if your docs folder has no markdown yet, a first
 that already has docs.
 
 ```sh
-npx docugate init --dir docs --title "Acme API"
+docugate init --dir docs --title "Acme API"
 ```
 
 Then push, and publish the space from your
@@ -52,9 +80,14 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npx docugate check
+      - run: npx docugate@0.1 check
 ```
 
+Pin the version in CI, as above, or add the package to the repository and run
+it from there. Without a pin, the rules being enforced can change between two
+runs of the same workflow, which turns a green build red with nothing in the
+commit to explain it.
+
 ## `openapi`
 
 Takes the OpenAPI 3 spec your backend already produces and writes the version
@@ -62,7 +95,7 @@ you want published: only the public paths, without sensitive fields, with keys
 in a stable order so it reviews cleanly in a pull request.
 
 ```sh
-npx docugate openapi --from http://localhost:3000/openapi.json \
+docugate openapi --from http://localhost:3000/openapi.json \
   --exclude "/internal/**" --redact passwordHash --out openapi.json
 ```
 
@@ -102,11 +135,13 @@ soon. See the
 
 ## `docugate.json`
 
+One per repository, at its root.
+
 | Key | Meaning |
 | --- | --- |
 | `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
 | `title` | The space's title. |
-| `sidebar` | File and folder names in the order the sidebar should show them. |
+| `sidebar` | File and folder names in the order the sidebar should show them. Orders this repository's own pages, not the whole space. |
 | `api.generate` | Defaults for `docugate openapi`. |
 
 ## Licence

package/dist/cli.js

@@ -8,7 +8,7 @@ const SITE = 'https://www.trydocugate.site';
 const HELP = `docugate: set up and check the docs DocuGate reads from your repository
 
 Usage
-  npx docugate <command> [options]
+  docugate <command> [options]
 
 Commands
   init        Set up this repository for DocuGate
@@ -70,7 +70,11 @@ function parse(argv) {
     return { command, flags, bools };
 }
 function fail(message) {
-    console.error(`${red('error')} ${message}\n${dim('Run `npx docugate --help` for usage.')}`);
+    // Phrased without a command name on purpose: this is the message somebody
+    // sees when they are already stuck, and it would be wrong for half of them.
+    // `docugate --help` is not a thing you can run if you reached this through
+    // npx, and `npx docugate --help` is not one if you installed it.
+    console.error(`${red('error')} ${message}\n${dim('See --help for usage.')}`);
     process.exit(2);
 }
 function version() {
@@ -140,7 +144,7 @@ async function main() {
                 }
                 else {
                     console.log(`${red('out of date')}  ${output} does not match ${from}.`);
-                    console.log(dim('Run `npx docugate openapi` and commit the result.'));
+                    console.log(dim('Run `docugate openapi` and commit the result.'));
                     process.exitCode = 1;
                 }
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository.",
   "type": "module",
   "bin": {