|
1 | | -> **Customize this file**: Tailor this template to your project by noting specific contribution types you're looking for, adding a Code of Conduct, or adjusting the writing guidelines to match your style. |
2 | | -
|
3 | 1 | # Contribute to the documentation |
4 | 2 |
|
5 | | -Thank you for your interest in contributing to our documentation! This guide will help you get started. |
| 3 | +Thanks for contributing to the BoxLite documentation. This guide is the **single |
| 4 | +source of truth** for how to make changes locally and how to ship them. |
| 5 | + |
| 6 | +## Setup (once) |
| 7 | + |
| 8 | +```bash |
| 9 | +git clone https://github.com/boxlite-ai/documentation.git |
| 10 | +cd documentation |
| 11 | +npm i -g mint # Mintlify CLI (Node 18+) |
| 12 | +brew install gh # GitHub CLI, used by deploy:preview |
| 13 | +``` |
| 14 | + |
| 15 | +## The four commands |
| 16 | + |
| 17 | +The same four `npm` scripts exist in every BoxLite content repo (`documentation`, |
| 18 | +`boxlite-website`, `boxlite-blog`) so the workflow is identical everywhere. |
| 19 | + |
| 20 | +| Command | What it does | When to use | |
| 21 | +|---|---|---| |
| 22 | +| `npm run dev` | Local preview at http://localhost:3000 (`mint dev`) | While editing | |
| 23 | +| `npm run check` | `mint validate && mint broken-links` | Before opening / updating a PR | |
| 24 | +| `npm run deploy:preview` | Pushes the current branch and opens (or reuses) a PR; Mintlify auto-builds a `*.mintlify.app` preview tied to that PR | To share work for review | |
| 25 | +| `npm run deploy:production` | Production = `main` only. Guards: must be on `main`, clean worktree, in sync with `origin/main`. Then instructs you to `gh pr merge` — merging a PR is the deploy. | To ship the docs | |
6 | 26 |
|
7 | | -## How to contribute |
| 27 | +### One canonical lifecycle (memorize this) |
8 | 28 |
|
9 | | -### Option 1: Edit directly on GitHub |
| 29 | +``` |
| 30 | +① git switch -c your-change from main |
| 31 | +② edit pages |
| 32 | +③ npm run dev preview locally |
| 33 | +④ git commit -am "..." |
| 34 | +⑤ npm run check validate + broken-links |
| 35 | +⑥ npm run deploy:preview push + open PR; Mintlify builds preview |
| 36 | +⑦ review the *.mintlify.app preview (light/dark, desktop/mobile) |
| 37 | +⑧ npm run deploy:production on main → prints the merge command |
| 38 | +⑨ gh pr merge <PR#> --merge --delete-branch |
| 39 | + main updates → Mintlify auto-deploys |
| 40 | + https://docs.boxlite.ai |
| 41 | +``` |
10 | 42 |
|
11 | | -1. Navigate to the page you want to edit |
12 | | -2. Click the "Edit this file" button (the pencil icon) |
13 | | -3. Make your changes and submit a pull request |
| 43 | +## Rules of the road |
14 | 44 |
|
15 | | -### Option 2: Local development |
| 45 | +- **`main` is protected.** Never push to it directly. Production happens only by |
| 46 | + **merging a PR**. There is no "deploy to production" command — `npm run deploy:production` |
| 47 | + guards the preconditions and tells you the merge command to run. |
| 48 | +- **Preview = PR.** Mintlify builds the preview when a PR is opened against `main` |
| 49 | + (not on a bare branch push). The Mintlify bot posts the `*.mintlify.app` link as a |
| 50 | + PR comment, and rebuilds on every push to the PR branch. |
| 51 | +- **`deploy:preview` may include just-committed work** that hasn't been reviewed — |
| 52 | + it is not a review artifact on its own. The *PR review* is. |
| 53 | +- **Why Docs has no `vercel`-style CLI deploy:** Mintlify only publishes through its |
| 54 | + Git integration; it has no production CLI deploy. The sibling Vercel repos |
| 55 | + (`boxlite.ai`, `blog.boxlite.ai`) follow the same lifecycle and use the same |
| 56 | + four script names; their `deploy:preview` shells out to `vercel deploy` because |
| 57 | + Vercel does have a CLI. The mental model is identical across all three repos. |
16 | 58 |
|
17 | | -1. Fork and clone this repository |
18 | | -2. Install the Mintlify CLI: `npm i -g mint` |
19 | | -3. Create a branch for your changes |
20 | | -4. Make changes |
21 | | -5. Navigate to the docs directory and run `mint dev` |
22 | | -6. Preview your changes at `http://localhost:3000` |
23 | | -7. Commit your changes and submit a pull request |
| 59 | +## Edit on GitHub (no clone) |
24 | 60 |
|
25 | | -For more details on local development, see our [development guide](development.mdx). |
| 61 | +1. Open the page on github.com/boxlite-ai/documentation. |
| 62 | +2. Click the pencil (**Edit this file**) icon — GitHub forks for you. |
| 63 | +3. Open a pull request. Mintlify will post a preview link on the PR. |
26 | 64 |
|
27 | 65 | ## Writing guidelines |
28 | 66 |
|
29 | | -- **Use active voice**: "Run the command" not "The command should be run" |
30 | | -- **Address the reader directly**: Use "you" instead of "the user" |
31 | | -- **Keep sentences concise**: Aim for one idea per sentence |
32 | | -- **Lead with the goal**: Start instructions with what the user wants to accomplish |
33 | | -- **Use consistent terminology**: Don't alternate between synonyms for the same concept |
34 | | -- **Include examples**: Show, don't just tell |
| 67 | +- **Active voice**: "Run the command", not "The command should be run". |
| 68 | +- **Address the reader directly** with "you". |
| 69 | +- **One idea per sentence.** |
| 70 | +- **Lead with the goal**, then the action. |
| 71 | +- **Use consistent terminology** — don't alternate synonyms for the same concept. |
| 72 | +- **Show, don't just tell** — include realistic examples. |
0 commit comments