To update documentation, find the page that you wish to change on developer.couchbase.com and click the Edit on GitHub button to open the backing markdown file.
Note: If the page you want to edit doesn't have the Edit on GitHub button it means that it hasn't been migrated to this contribution process yet. In this case, you can file a new issue.
From there you can click the Edit button to write changes on GitHub. Make sure to check the Style Guide in the next section to get familiar with the writing rules.
Once you are done with edits scroll to the bottom of the page and select the create new branch option.
Then click the Propose file change button which will open a PR with the changes. Someone with push access to the master branch will then review the changes and merge the PR.
Use Git to clone the Couchbase Mobile Portal repository to your local disk:
git clone git@github.com:couchbaselabs/couchbase-mobile-portal.git
cd couchbase-mobile-portal
You must have ruby 2.1.0+ installed on your system.
$ ruby -vIf the version is lower than 2.1.0 you must update the version (via brew or using rvm):
$ brew install rubyand then open a new terminal to refresh the environment.
$ cd md-docs
$ gem install bundler
$ bundle installNote: if you encounter an error saying that nokogiri isn't installed follow the steps in this guide to install it on your system.
$ cd md-docs
// to build the 1.3 docs
$ bundle exec jekyll serve --config _config.yml,_config.13.yml --livereload
// or, to build the 1.4 docs
$ bundle exec jekyll serve --config _config.yml,_config.14.yml --livereload
// or, to build the 2.0 docs
$ bundle exec jekyll serve --config _config.yml,_config.20.yml --livereloadBrowse the docs at http://localhost:4000/index.html.
The command is using the --livereload flag which will automatically reload the browser window when a change is saved. This only works in Chrome and the LiveReload Chrome Extension must be installed. Once it's installed you should see the small circle filled in gray which indicates that the extension is connected to the Jekyll web server.
To contribute to Guides, API references or REST APIs, read the following. You don't need to build the site locally. Just find the content that needs editing and submit a pull request.
To add code tabs in your markdown file add the following html tag:
<div class="tabs"></div>Then use code fencing with the + character to specify that its part of code tabs.
Objective-C -> ```objective-c+
Swift -> ```swift+
Java -> ```java+
C# -> ```c+
GitHub will render 4 code blocks one after the other but don't worry, the tabs will be displayed as expected on the site.
REST APIs are documented using Swagger. Read more in the readme of the swagger folder.
API references are documented in https://github.com/couchbaselabs/couchbase-lite-api.
- Code tabs in markdown
- Table styles
- Pragma marks on REST API doc titles
- Styling blockquotes
- Highlight Objective-C with C
Release notes are generated using the GitHubReleaseNotes tool.
- Download the latest release
- Unzip and navigate to the folder:
cd release-notes-tool - Generate the release notes in Couchbase Mobile's custom XML format:
mono bin/Debug/ReleaseNotesCompiler.CLI.exe update --owner couchbase --repository couchbase-lite-ios --targetcommitish master -u USER -p PASS -m 1.3 --exportxml
Repositories to generate release notes for:
- couchbase-lite-net
- couchbase-lite-ios
- couchbase-lite-java-core
- couchbase-lite-java
- couchbase-lite-android
- sync_gateway
The tool outputs the XML for each repository in the current directory.
- For SG, copy the
articletodocs/src/guides/sync-gateway/release-notes.xml. - For CBL, copy the
topictodocs/src/guides/couchbase-lite/release-notes.xml.
- Create a new key-value pair for the new version (on cms-qa for example).
- Create a new documentation set for the new version (on cms-qa for example)
- Make the latest documentation set the current one and uncheck the previous one if necessary.
To validate links, generate the docs and run the link checker tool.
./build.sh 20
linkchecker tmp/index.html