Anyone can edit these docs, you don't need to be a developer. There's nothing to install, clone, or set up: ask Claude to do the work and it handles the mechanics.
- Ask Claude to draft the change. Describe what's wrong or missing in plain language ("the X page doesn't mention Y — add a section") and let Claude write the copy. You don't need to find the right file or write Markdown yourself.
- Ask Claude to open the PR. You don't have to touch Git or GitHub.
- Check the preview. When CI passes, a review environment URL is commented on your PR. Open it and confirm your change looks right, this is the one step Claude can't do for you.
- Post your PR in #team-tech-writers. Docs owners are added automatically as code owners, but posting in the channel is what actually gets a reviewer on it.
- A docs owner reviews and the PR can be merged.
That's it. If you're curious what Claude is working from, the repo's CLAUDE.md
holds the detailed contribution guidance.
Additional documentation health metrics may be added here in the future (e.g., number of documents, build status, etc.)
This repository contains the source files for the official Bitrise documentation. It is intended for reference and transparency purposes only.
The latest, user-friendly documentation is available at:
This repository is not intended for open source contributions. If you have questions or feedback about Bitrise or its documentation, please use the support channels provided on our website.
If you've never used Node.js or a docs site before, no problem — these steps walk you through everything.
You need two things on your machine:
-
Node.js — the JavaScript runtime that powers Docusaurus. Get the LTS version from nodejs.org (or run
brew install nodeon macOS). After installing, open a fresh terminal and confirm it's there:node --version # should print v18.x or higher npm --version # should print 9.x or higher
-
Git — to clone this repo. Check with
git --version. macOS prompts you to install it on first run; on other systems grab it from git-scm.com.
git clone git@github.com:bitrise-io/docs.git
cd docsFrom inside the docs/ folder:
npm installThis downloads everything Docusaurus needs into a node_modules/ folder. It's safe to ignore the deprecation warnings; the install takes a minute or two.
npm startDocusaurus boots a development server, then opens http://localhost:3000 in your browser automatically. Every page is served at /en/... — for example http://localhost:3000/en/bitrise-ci.html.
The dev server hot-reloads: edit any .md / .mdx file under docs/ (or any partial under src/partials/), save, and the browser refreshes within a second.
To stop the server, press Ctrl+C in the terminal.
When you want to verify the production build (same output that ships to docs.bitrise.io):
npm run buildThe output lands in build/. To preview it locally:
npm run serve| You want to... | Edit this |
|---|---|
| Change the text of a page | docs/<section>/.../<page>.md or .mdx |
| Change a piece of content reused across many pages | src/partials/<readable-name>.mdx |
Change the landing page (the / portal) |
src/pages/index.tsx |
| Change site-wide navbar / footer / colors | docusaurus.config.ts, src/css/custom.css |
| Add a new image | drop it under static/img/ and reference it as /img/your-file.png |
npm: command not found— Node.js isn't installed (or your terminal hasn't picked it up). Reinstall from nodejs.org and open a new terminal window.- Build errors mentioning MDX — usually a stray
<word>or{kebab-case}placeholder in a Markdown file is being parsed as JSX. The error message points at the file and line; wrap the offending text in backticks (`<word>`) or escape with HTML entities (<word>). - Port 3000 already in use — pass a different port:
npm start -- --port 3001. - Browser shows an empty page after editing — check the terminal for compile errors; the dev server pauses rendering until it can recompile.