Skip to content

imolorhe/reaction-docs

 
 

Repository files navigation

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, for static-site documentation generation
  • Markdown for Docs
  • React for components
  • highlight.js for JavaScript, HTML, CSS, shell syntax highlighting
  • Prism.js for JSX, GraphQL syntax highlighting
  • Algolia DocSearch
  • ESLint configured with Reaction Commerce eslint config
  • LiveReload during development
  • Docker

Getting started

git clone git@github.com:reactioncommerce/reaction-docs.git
cd reaction-docs
bin/setup
docker-compose up

Open localhost:4000

Documenting

  1. Add a new Markdown file in public-docs.
  2. At the start of the file, add the required frontmatter:
---
id: doc2
title: document number 2
---
  1. Add the Markdown file to the table of contents, at website/sidebars.json
  2. The server uses LiveReload, so as soon as you save, you should see the changes at localhost:4000.

For more Markdown features, including autogenerated table of contents, refer to Docusaurus docs.

Adding images

Save the image in website/static/assets and reference it like this:

![](/assets/admin-dashboard.png "Reaction Dashboard")

Cross Linking

Reference other articles by their filename:

Refer to the [FAQs](faqs.md) article

Syntax highlighting

Supports js, jsx, graphql, html, sh, git, yaml and more.

Developing

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

docker-compose up -d && docker-compose logs -f

Linting

docker-compose run --rm web yarn lint
docker-compose run --rm web yarn lint:fix:eslint

Running commands

docker-compose run --rm web [...] will run any command inside a Docker container and then remove the container.

Restart

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

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

  1. Add a new version
docker-compose run --rm web yarn run version <version-number>
  1. Restart the container:
docker-compose down && docker-compose up
  1. Run locally to confirm the version number has been changed on localhost:4000, and the previous version has been added to localhost:4000/versions list.

  2. If all things look good, push the branch up to make a pull request.

  3. Merge to master to auto-deploy

Deploying

Merge to staging branch

Merging to staging will trigger a CircleCI build to https://reaction-docs-staging.reactioncommerce.com/

Merge to master branch

Merging to master will trigger a CircleCI build to http://reaction-docs-production.netlify.com

Packages

No packages published

Languages

  • CSS 49.2%
  • JavaScript 38.8%
  • Dockerfile 7.0%
  • Shell 4.2%
  • HTML 0.8%