Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reactioncommerce/reaction-docs
Documentation for Reaction, Reaction Platform, Example Storefront, and other supporting services.
https://github.com/reactioncommerce/reaction-docs
reaction-documentation reactioncommerce
Last synced: about 2 months ago
JSON representation
Documentation for Reaction, Reaction Platform, Example Storefront, and other supporting services.
- Host: GitHub
- URL: https://github.com/reactioncommerce/reaction-docs
- Owner: reactioncommerce
- License: gpl-3.0
- Created: 2015-12-21T01:45:49.000Z (about 9 years ago)
- Default Branch: trunk
- Last Pushed: 2021-08-03T19:57:42.000Z (over 3 years ago)
- Last Synced: 2024-08-21T09:15:17.476Z (4 months ago)
- Topics: reaction-documentation, reactioncommerce
- Language: CSS
- Homepage:
- Size: 62.7 MB
- Stars: 68
- Watchers: 25
- Forks: 137
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# reaction-docs
📝 `reaction-docs` is the new static documentation generator for all Reaction Commerce projects.
## Requirements
- Node, 6.x and above
- Yarn
- Docker
## Stack
- [Docusaurus](https://github.com/facebook/docusaurus/), for static-site documentation generation
- Markdown for Docs
- React for components
- [highlight.js](https://github.com/isagalaev/highlight.js) for JavaScript, HTML, CSS, shell syntax highlighting
- [Prism.js](https://prismjs.com/) for JSX, GraphQL syntax highlighting
- [Algolia DocSearch](https://community.algolia.com/docsearch/)
- ESLint configured with Reaction Commerce eslint config
- LiveReload during development
- Docker
## Contributing documentation
### Run the docs website locally
```
git clone [email protected]:reactioncommerce/reaction-docs.git
cd reaction-docs
bin/setup
docker-compose up
```
Open http://localhost:4242
### Update existing documentation
To update docs for the current released version of Reaction, edit existing Markdown files in `website/versioned_docs`.
1. 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.
1. Edit the file and save.
1. Go to `http://localhost:4242/docs/` 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 `public-docs/cart.md` file.
1. Edit the file and save.
1. Go to `http://localhost:4242/docs/next/` 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 `public_docs`:
1. At the start of the file, add the required frontmatter:
```md
---
id: doc2
title: document number 2
---
```
1. Add the Markdown file to the table of contents, at `website/sidebars.json`.
1. When you update `sidebars.json`, you'll need to restart the app to see changes. Restart the app.
1. Go to `http://localhost:4242/docs/next/` to see your new file locally.
### Tips for documenting
- To add images, save the image in website/static/assets and reference it like this:
```md
```
- To link to other articles, reference other articles by their filename:
```md
Refer to the [FAQs](faqs.md) article
```
- To enable code syntax highlighting, add `js`, `jsx`, `graphql`, `html`, `sh`, `git`, `yaml` and [more](https://github.com/reactioncommerce/reaction-docs-static/issues/47) after the ```.
- For more Markdown features, including autogenerated table of contents, refer to [Docusaurus docs](https://docusaurus.io/docs/en/doc-markdown.html).
### Sign off your commits
We use the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) 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
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.
## Contributing development
The Header, Footer, index page and version pages are developed in React and CSS within the `website/core` and `website/static` directories. Site configuration details are managed in `website/siteConfig.js`.
### Logging
```sh
docker-compose up -d && docker-compose logs -f
```
### Linting
```sh
docker-compose run --rm web yarn lint
```
```sh
docker-compose run --rm web yarn lint:fix:eslint
```
### Building
```sh
docker-compose run --rm web yarn build
```
### Running commands
`docker-compose run --rm web [...]` will run any command inside a Docker container and then remove the container.
### Restart
```sh
docker-compose run --rm web yarn install \
&& docker-compose down --rmi local \
&& docker-compose build \
&& docker-compose up
```
### Tests
Tests are stubbed out for now.
## Versioning
Add a new version
```sh
docker-compose run --rm web yarn run version
```
Rename an existing version to a new name
```sh
docker-compose run --rm web yarn run rename-version
```
See [Versioning guide](https://docusaurus.io/docs/en/1.1.4/versioning.html) for more.
## Releasing a new version
1. Add a new version
```sh
docker-compose run --rm web yarn run version
```
2. Restart the container:
```sh
docker-compose down && docker-compose up
```
3. Run locally to confirm the version number has been changed in the header on http://localhost:4242, and the previous version has been added to the http://localhost:4242/versions list.
4. If all things look good, push the branch up to make a pull request.
5. Merge to `trunk` to auto-deploy
## Deploying
### Merge to `staging` branch
Merging to `staging` will trigger a CircleCI build to https://reaction-docs-staging.reactioncommerce.com/ using Netlify.
### Merge to `trunk` branch
Merging to `trunk` will trigger a CircleCI build to https://docs.reactioncommerce.com/ using Netlify.
## Algolia search configuration
Search is generously provided by [Algolia DocSearch](https://community.algolia.com/docsearch/what-is-docsearch.html). The configuration for this site's search available [here](https://github.com/algolia/docsearch-configs/blob/master/configs/reactioncommerce.json) and can be configured by sending a pull request to that repository. More details [here](https://community.algolia.com/docsearch/config-file.html).