R3 Product Documentation
The documentation source files are under the
../content directory in the
corda-docs-portal repository, and is written in markdown.
The HTML documentation output is generated using Hugo. You can build and edit the docs locally using npm and a markdown editor.
Build and edit the docs locally
- Install npm.
- Install a markdown editor of your choice.
- Fork the
corda/corda-docs-portalrepository, and clone your fork.
- From the root directory of the repository, run
npm install. This installs all the required modules to build the documentation locally.
- Open a new branch and create/edit the relevant markdown file(s) in the
hugo server --watch=falseto build the documentation locally. Please note that due to an existing unresolved Hugo bug that manifests for larger websites like
docs.r3.com, at the moment it is not possible to build the documentation locally with dynamic content refresh - you need to
CTRL-Cand run the build again after you make changes to your content. We hope that Hugo will resolve this soon!
- Navigate to
https://localhost:1313to view the locally built documentation.
- Push your changes to GitHub and open a pull request.
Keep your fork in sync with the documentation
To best way to keep your fork in sync with the main documentation repository is to add it an
upstream remote after you create your fork.
Add the upstream remote
To add an upstream remote:
git remote add upstream https://github.com/corda/corda-docs-portal.git
The URL of a remote can be changed using the
git remote set-url command.
View your remotes
To view your remotes:
git remote -v
Remove a remote
If you need to remove a remote:
git remote rm remote-name
Get the latest updates from the upstream remote
To update your current branch, rebase on the latest changes from the upstream remote. This will protect any unmerged commits from being overwritten:
git rebase upstream/main
Tell us what you think
We would greatly appreciate your feedback about the documentation content, website, and repository.
- Chat with us on our
#docschannel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
- Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.
- Help us to improve the docs by contributing to the content directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions. Learn how to do this here.