diff --git a/docs/README.md b/docs/README.md index 0c6c2c27..b62df12e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,41 +1,55 @@ -# Website +# Documentation Website -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. +The Documentation Website is built using [Docusaurus](https://docusaurus.io/). + +If you want to make a contribution to the documentation, please follow these +instructions: + +1. Fork the `master` branch of this repository to your GitHub profile. Do not fork the `gh-pages` branch as it only contains the "built" version. +2. Create a branch to work on your changes +3. Test your changes locally (see below for instructions on how to use Docusaurus) +4. Create a Pull Request against the `master` branch to submit your changes + + +## Install and Develop with Docusaurus + +This is not a tutorial on how to use Docusaurus. Please refer to Docusaurus documentation. ### Installation +On your local fork of the Documentation, use `yarn` to install +the Docusaurus dependencies. + ``` $ yarn ``` ### Local Development -``` -$ yarn start -``` +Once the dependencies are installed, you can make changes to the documentation source files. + +Typically, only the files located under `/docs`, `/src` and `/blog` should be changed. -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +Changes to the navigation and footer are made to the `docusauraus.config.js` file. -### Build +To test locally your changes, run: ``` -$ yarn build +$ yarn start ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +This command starts a local development server and opens up a browser window. Most changes are reflected live +without having to restart the server. -### Deployment +## Test builds -Using SSH: +A GitHub action is define to test builds. It will run on push to your fork. -``` -$ USE_SSH=true yarn deploy -``` +You may have to enable workflows on your fork before they are run. -Not using SSH: +## Submit changes -``` -$ GIT_USER= yarn deploy -``` +Once you are satisfied with your changes and the `Build GitHub Pages No Deploy` action has +passed successfully, then create and submit a Pull Request against the `master` branch of +the repository. -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.