reaction-docs is the new static documentation generator for all Reaction Commerce projects.
- Node, 6.x and above
- Docusaurus, for static-site documentation generation
- Markdown for Docs
- React for components
- Prism.js for JSX, GraphQL syntax highlighting
- Algolia DocSearch
- ESLint configured with Reaction Commerce eslint config
- LiveReload during development
Run the docs website locally
git clone email@example.com:reactioncommerce/reaction-docs.git cd reaction-docs bin/setup docker-compose up
Update existing documentation
To update docs for the current released version of Reaction, edit existing Markdown files in
- Find the Markdown file you want to edit in the latest version's folder, at
website/versioned_docs/version-CURRENTVERSION. If the document you want to edit is not in that folder, check in previous versions' folders until you find the latest one.
- Edit the file and save.
- Go to
http://localhost:4242/docs/<YOURMARKDOWNFILE_ID>to see your changes locally.
Documenting unreleased features, changes
To update docs of unreleased features, you will need to edit existing Markdown files in
public_docs. For example, if you were documenting upcoming Reaction API changes to Cart that are merged into
trunk but not yet tagged in a release, you'd update the
- Edit the file and save.
- Go to
http://localhost:4242/docs/next/<YOURMARKDOWNFILE_ID>to see your changes locally.
Documenting new, unreleased features
To create brand new documentation files for unreleased code that has previously not been documented, you will need to create new files in
- At the start of the file, add the required frontmatter:
--- id: doc2 title: document number 2 ---
- Add the Markdown file to the table of contents, at
- When you update
sidebars.json, you'll need to restart the app to see changes. Restart the app.
- Go to
http://localhost:4242/docs/next/<YOURMARKDOWNFILE_ID>to see your new file locally.
Tips for documenting
- To add images, save the image in website/static/assets and reference it like this:
!(/assets/admin-dashboard.png "Reaction Dashboard")
- To link to other articles, reference other articles by their filename:
Refer to the [FAQs](faqs.md) article
To enable code syntax highlighting, add
yamland more after the ```.
For more Markdown features, including autogenerated table of contents, refer to Docusaurus docs.
Sign off your commits
We use the Developer Certificate of Origin (DCO) in lieu of a Contributor License Agreement for all contributions to Reaction Commerce open source projects. We request that contributors agree to the terms of the DCO and indicate that agreement by signing off all commits made to Reaction Commerce projects by adding a line with your name and email address to every Git commit message contributed:
Signed-off-by: Jane Doe firstname.lastname@example.org
You can sign off your commit automatically with Git by using git commit -s if you have your user.name and user.email set as part of your Git configuration.
We ask that you use your real name (please no anonymous contributions or pseudonyms). By signing your commit you are certifying that you have the right to submit it under the open source license used by that particular Reaction Commerce project. You must use your real name (no pseudonyms or anonymous contributions are allowed.)
We use the Probot DCO GitHub app to check for DCO signoffs of every commit.
If you forget to sign off git your commits, the DCO bot will remind you and give you detailed instructions for how to amend your commits to add a signature.
The Header, Footer, index page and version pages are developed in React and CSS within the
website/static directories. Site configuration details are managed in
docker-compose up -d && docker-compose logs -f
docker-compose run --rm web yarn lint
docker-compose run --rm web yarn lint:fix:eslint
docker-compose run --rm web yarn build
docker-compose run --rm web [...] will run any command inside a Docker container and then remove the container.
docker-compose run --rm web yarn install \ && docker-compose down --rmi local \ && docker-compose build \ && docker-compose up
Tests are stubbed out for now.
Add a new version
docker-compose run --rm web yarn run version <version>
Rename an existing version to a new name
docker-compose run --rm web yarn run rename-version <currentVersion> <newVersion>
See Versioning guide for more.
Releasing a new version
- Add a new version
docker-compose run --rm web yarn run version <version-number>
- Restart the container:
docker-compose down && docker-compose up
If all things look good, push the branch up to make a pull request.
staging will trigger a CircleCI build to https://reaction-docs-staging.reactioncommerce.com/ using Netlify.
trunk will trigger a CircleCI build to https://docs.reactioncommerce.com/ using Netlify.