This repository contains the documentation for YugabyteDB available at https://docs.yugabyte.com/
Please open an issue to suggest enhancements.
Contributing to YugabyteDB Docs
YugabyteDB docs are based on the Hugo framework and use the Material Docs theme.
- Hugo framework: http://gohugo.io/overview/introduction/
- Material Docs theme: http://themes.gohugo.io/material-docs/
Step 1. Initial setup
Follow these steps if this is the first time you are setting up for working on the docs locally.
Fork this repository on GitHub and create a local clone of your fork. This should look something like below:
git clone firstname.lastname@example.org:<YOUR_GITHUB_ID>/yugabyte-db.git
Add the original repository as an upstream remote:
git remote add --track master upstream https://github.com/yugabyte/yugabyte-db.git
Install Hugo. For example, on a Mac, you can run the following commands:
brew update brew install hugo brew install npm
Install node modules as shown below:
Step 2. Update your repo and start the local webserver
The assumption here is that you are working on a local clone of your fork. See the previous step.
- Rebase your fork to fetch the latest docs changes: Ensure you are on the master branch.
$ git checkout master
Now rebase to the latest changes.
$ git pull --rebase upstream master $ git push origin master
- Start the local webserver on
127.0.0.1interface by running the following:
$ npm start
You should be able to see the local version of the docs by browsing to: http://localhost:1313/
Note #1 that the URL may be different if the port 1313 is not available. In any case, the URL is printed out on your shell as shown below.
Web Server is available at //localhost:1313/ (bind address 0.0.0.0) Press Ctrl+C to stop
Note #2 To start the webserver on some other IP address (in case you want to share the URL of your local docs with someone else), do the following:
YB_HUGO_BASE=<YOUR_IP_OR_HOSTNAME> npm start
You can now share the following link:
Step 3. Make changes
It is suggested that you create and checkout a feature branch off
master for your changes:
$ git branch <feature branch name> master $ git checkout <feature branch name>
Make the changes locally and test them on the browser.
Once you are satisfied with your changes, commit them to your local branch. You can do this by running the following command:
# Add files you have made changes to. $ git add ... # Commit these changes. $ git commit
Step 4. Submit a pull request
Create a pull request once you are ready to submit your changes.
We will review your changes, add any feedback and once everything looks good merge your changes into the mainline.
Note: YCQL docs are still using an old method. Follow these instructions for YSQL, but use these instructions just as a reference for YCQL.
Generate API syntax diagrams
Download the latest RRDiagram JAR file (
rrdiagram.jar). You can find it on the release page, or you can try running the following command.
wget $(curl -s https://api.github.com/repos/Yugabyte/RRDiagram/releases/latest \ | grep browser_download_url | cut -d \" -f 4)
Note: Alternatively, you can manually build the JAR file as described in the build section of the
Run the diagram generator using the following command:
java -jar rrdiagram.jar content/latest/api/ysql/syntax_resources/ysql_grammar.ebnf \ content/latest/api/ysql/syntax_resources/
To display helpful
WARNINGmessages, end the last argument with
The following files will be regenerated if they exist:
Note: To see help, run
java -jar rrdiagram.jar(without arguments).
Add a new docs page
You may need to add a new docs page if you are adding a new command that doesn't belong in the existing doc pages.
Add new rules to the source grammar file:
Prepare the new diagram and grammar files by creating the following empty files:
<rules>, use a comma-separated list of rule names that you want in your new docs page.
Example: for the YSQL 'COPY' command, the diagram and grammar files are the following:
Create the docs page file:
Use the existing files in that directory as examples. For
<name>, follow the naming convention exhibited by the other files. For YSQL, note the usage of the template
Example: for the YSQL
COPYcommand, the created file is the following:
Update the index page files:
Ensure that no
WARNINGs are thrown related to the rules that you added.
Check the new docs page and index pages to make sure that there are no broken links.
Edit rules in a docs page
You may need to add or edit grammar rules in an existing docs page.
Add or edit rules in the source grammar file:
Rename the diagram and grammar files if needed:
Edit the contents of the docs page file:
Ensure that no
WARNINGs are thrown related to the rules that you added or edited.
Check the modified docs page to make sure that there are no broken links.
- To force the page to be re-rendered, you may need to save the docs page file (for example,