Build the documentation
The documentation source files are under the ../content
directory in the corda-docs-portal
repository, and are written in markdown
format.
The documentation output in HTML format is generated using Hugo. You can build
and edit the docs locally using npm
and a markdown
editor.
Build the docs locally
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
Steps:
- Install npm
- Install a markdown editor of your choice.
- Fork the
corda/corda-docs-portal
repository, 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
content
directory. - Run
hugo server
to build the documentation locally. After you make changes, the content should refresh dynamically. - If the
hugo server
command didn’t work, runhugo server --watch=false
. Please note that due to an existing unresolved Hugo bug that manifests for larger websites likedocs.r3.com
, it may not possible to build the documentation locally with dynamic content refresh - you need toCTRL-C
and run the build again after you make changes to your content. - Navigate to
https://localhost:1313
to view the locally built documentation. - Push your changes to GitHub and open a pull request.
Contribute to documentation updates
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
To propose an update to the public released Corda docs, fork the corda-docs-portal
repository, make your changes, and submit a pull request targeting the main
branch in the upstream repository from your fork.
Steps
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
- Fork the corda-docs-portal repository and add it as upstream (or sync your existing
fork with the upstream repo’s
main
branch - see below for instructions). - Edit the documentation files in a new branch in your fork.
- Commit and push the changes to your fork.
- Create a pull request targeting the
main
branch in the upstream repo. Your pull request will be auto-assigned to R3’s Technical Writing Team for review.
Where are the files
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
The documentation for all released versions of Corda Open Source Edition, Corda Enterprise, Corda Enterprise Network Manager (CENM), and Corda 5 are organized in sub-directories, following the version and then the product flavor. For example:
../corda-docs-portal/content/en/platform/corda/4.12/community/
Edit web pages directly in Visual Studio Code
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
After installing Hugo and Visual Studio Code, run the following commands per operating system.
Windows Powershell (assuming there are no spaces in your directory names):
.\serve_and_edit.ps1
Mac/Linux:
make local-serve-and-edit
Or if you want to use Docker:
hugo-serve-and-edit
As a result, there will be an extra icon in the title bar of your local docs site, which should open the current page in Visual Studio Code:
![Visual Studio Code](/en/images/hugo-vscode-page-edit.png)
Edit web pages directly in Atom
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
After installing Hugo and Atom (you need to install the open package!), run the following commands per operating system.
If this is your preferred editor, then consider setting HUGO_PARAMS_EDITOR
in your environment.
Windows Powershell:
$env:HUGO_PARAMS_EDITOR="atom"
.\serve_and_edit.ps1
Mac/Linux:
export HUGO_PARAMS_EDITOR=atom
make local-serve-and-edit
Or if you want to use Docker:
export HUGO_PARAMS_EDITOR=atom
make hugo-serve-and-edit
Keep your fork in sync with the upstream repo
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
The best way to keep your fork in sync with the main documentation repository is to add it as the upstream
repository after
you create the fork.
Add the upstream repo
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
To add upstream
:
cd <to-your-fork-repo-dir>
git remote add upstream git://github.com/corda/corda-docs-portal.git
The URL of a remote can be changed using the git remote set-url
command.
You would normally only need do this once after you create the fork.
If you are not using an ssh
key to access GitHub, use the https
URL instead:
git remote add upstream https://github.com/corda/corda-docs-portal.git
If you’ve got the upstream repo URL wrong, you can change the upstream repo URL using the following command:
git remote set-url upstream https://github.com/corda/corda-docs-portal.git
View your remotes
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
To view your remotes:
git remote -v
You should see something like this:
git remote -v
origin git@github.com:my-github-username/corda-docs-portal.git (fetch) # YOUR FORK
origin git@github.com:my-github-username/corda-docs-portal.git (push)
upstream git@github.com:corda/corda-docs-portal.git (fetch) # THE ORIGINAL REPO
upstream git@github.com:corda/corda-docs-portal.git (push)
Alternatively, if you are accessing GitHub without an ssh
key:
git remote -v
origin https://github.com/my-github-username/corda-docs-portal.git (fetch) # YOUR FORK
origin https://github.com/my-github-username/corda-docs-portal.git (push)
upstream https://github.com/corda/corda-docs-portal.git (fetch) # THE ORIGINAL REPO
upstream https://github.com/corda/corda-docs-portal.git (push)
Remove the upstream repo
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
If you need to remove the upstream
repo for any reason:
git remote rm upstream
Keep the upstream repo updated
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
To keep the upstream updated (in other words, to fetch
all the stuff from the upstream repo):
git fetch upstream
Sync your fork
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
There are two ways in which you can do this - merge
or rebase
.
Merge the upstream with your fork
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
To sync your fork via merge
:
git merge upstream/main main
This command will merge the latest changes from the main
branch of the upstream into your local fork’s main
branch.
To merge a different branch, replace main
with the name of that branch for both repos.
For example, to merge a branch called example-branch
, run the following:
git checkout example-branch
git merge upstream/example-branch example-branch
Rebase the upstream with your fork
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
git rebase upstream/main
To rebase a different branch, replace main
with the name of that branch for both repos.
For example, to rebase a branch called example-branch
, run the following:
git checkout example-branch
git rebase upstream/example-branch example-branch
Push from the local fork main to the origin fork main
![Click to copy the section link. heading-link-icon](/icons/chain-icon.png)
After the merge
or rebase
, don’t forget to push
your local fork’s main branch (or another branch you’ve synced) to the fork origin main
(or another corresponding branch).
For example:
git push origin main
Was this page helpful?
Thanks for your feedback!
Chat with us
Chat with us on our #docs channel 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.
Propose documentation improvements directly
Help us to improve the docs by contributing 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.
We're sorry this page wasn't helpful. Let us know how we can make it better!
Chat with us
Chat with us on our #docs channel 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 an issue
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.
Propose documentation improvements directly
Help us to improve the docs by contributing 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.