Contributing to CockroachDB Docs

The CockroachDB docs are open source just like the database itself. We welcome your contributions!

Setup

Fork the CockroachDB docs repository.
Create a local clone of your fork.
CockroachDB uses Jekyll to transform Markdown and layout files into a complete, static HTML site. We also use htmltest to check the generated HTML for errors (broken internal and external links, missing images, etc.).

Install Jekyll, htmltest, and some other dependencies so you can view doc changes locally:
```
$ cd path/to/docs
$ make bootstrap
```
Learn the essentials of our Docs Structure.
Review our simple Style Guide.

Get Started

Once you're ready to contribute:

Create a new local branch for your work:

$ cd path/to/docs
$ git checkout -b "<your branch name>"

Make your changes.

Note that there are distinct directories for each documented version of CockroachDB. For example, docs for CockroachDB v1.0 are in the v1.0 directory, whereas docs for CockroachDB v1.1 are in the v1.1 directory.
Build and test the docs locally.
Commit your changes.
Push to your local branch to your remote fork.
Back in the CockroachDB docs repo, open a pull request and assign it to jseldess. If you check the Allow edits from maintainers option when creating your pull request, we'll be able to make minor edits or fixes directly, if it seems easier than commenting and asking you to make those revisions, which can streamline the review process.

We'll review your changes, providing feedback and guidance as necessary. Also, Teamcity, the system we use to automate tests, will run the markdown files through Jekyll and then run htmltest against the resulting HTML output to check for errors. Teamcity will also attempt to sync the HTML to an AWS server, but since you'll be working on your own fork, this part of the process will fail; don't worry about the Teamcity fail status.

Keep Contributing

If you want to regularly contribute to the CockroachDB docs, there are a few things we recommend:

Make it easy to bring updated docs into your fork by tracking us upstream:

$ git remote add --track master upstream https://github.com/cockroachdb/docs.git

When you're ready to make your next round of changes, get our latest docs:
```
$ git fetch upstream
$ git merge upstream/master
```
Repeat the write, build, push, pull flow from the Get Started section above.

Docs Structure

Pages
Sidebar

Pages

We provide documentation for each major version of CockroachDB. The pages for each version are found in a directory named for the version. For example, docs for CockroachDB v1.0 are in the v1.0 directory, whereas docs for CockroachDB v1.1 are in the v1.1 directory.

Within each version directory, each page must be an .md file written in the redcarpet dialect of Markdown. File names should be lowercase with a dash between words, and should brief but descriptive.

Example:

name-of-your-file.md

Markdown pages must start with the following front-matter:

---
title: Title of Page
summary: Short description of page for SEO
---

Field	Description	Default
`title`	Used as the h1 header and written in title-case.	Nothing
`summary`	Used as the page's `meta description` for SEO. Keep this under 155 characters. Consider using the first sentence of the page, or something similar.	Nothing

Optionally, you can specify other fields in the front-matter:

Field	Description	Default
`toc`	Adds an auto-generated table of contents to the right of the page body (on standard screens or at the top of the page (on smaller screen).
`toc_not_nested`	Limits a page's TOC to h2 headers only.	`false`
`allowed_hashes`	Specifies a list of allowed hashes that don't correspond to a section heading on the page.	Nothing
`asciicast`	Adds code required to play asciicasts on the page. See Asciicasts for more details.	`false`
`feedback`	Adds "Yes/No" feedback buttons at the bottom of the page. See Feedback Widget for more details.	`true`
`contribute`	Adds "Contribute" options at the top-right of the page. See Contributing Options for more details.	`true`
`redirect_from`	Specifies other internal URLs that should redirect to the page. See Client-Side Redirects	Nothing
`twitter`	Adds code required to track the page as part of a Twitter campaign	`false`
`no_sidebar`	If `true`, removes the sidebar from a page. See Sidebar for more details.	Nothing
`block_search`	If `true`, adds meta tags to the header that excludes the page from search indexing/caching.	Nothing
`back_to_top`	If `true`, adds a back-to-top button to the page. This is only helpful in cases where the page is very long and there is no page toc, e.g., the Full SQL Grammar page.

Page TOC

The CockroachDB Jekyll theme can auto-generate a page-level table of contents listing all h2 and h3 headers or just all h2 headers on the page. Related files: js/toc.js and _includes/toc.html.

To add a page TOC, set toc: true in the page's front-matter.
To omit a page TOC from the page, set toc: false in the page's front-matter.
By default, a page TOC includes h2 and h3 headers. To limit a page TOC to h2 headers only, set toc_not_nested: true in the page's front-matter.

Auto-Included Content

Some pages auto-include content from the _includes directory. For example, each SQL statement page includes a syntax diagram from _includes/<version>/sql/diagrams, and the build-an-app-with-cockroachdb.md tutorials include code samples from _includes/<version>/app.

The syntax for including content is {% include {{ page.version.version }}/<filepath> %}, for example, {% include {{ page.version.version }}/app/basic-sample.rb %}.

Version Tags

New and changed features should be called out in the documentation using version tags.

To add a version tag to a paragraph, place <span class="version-tag">New in vX.X:</span> at the start of the paragraph, e.g:
```
<span class="version-tag">New in v1.1:</span> The `user_privileges` view identifies global privileges.
```
To add a version tag to a heading, place <span class="version-tag">New in vX.X</span> to the right of the heading, e.g.:
```
## SQL Shell Welcome <div class="version-tag">New in v1.1</div>
```

When calling out a change, rather than something new, change New in vX.X to Changed in vX.X.

Allowed Hashes

In a page's front-matter, you can specify a list of allowed hashes that don't correspond to a section heading on the page. This is currently used for pages with JavaScript toggle buttons, where the toggle to activate by default can be specified in the URL hash. If you attempt to link to, for example, page-with-toggles.html#toggle-id without listing toggle-id in allowed_hashes, our HTML tester will complain that toggle-id does not exist on the page. Listing a hash in allowed_hashes will generate a dummy element with that ID at the top of the page, which keeps our HTML tester happy.

Here's an example from a page with OS toggles:

allowed_hashes: [os-mac, os-linux, os-windows]

Asciicasts

Install asciinema.
Size your shell window to be a bit narrower than our code blocks.
Initiate an asciicast with asciinema rec -c "/bin/bash -l". This makes the asciicast use your shell's appearance.
Press CTRL + D to stop recording.
Press Enter to upload the recording to asciinema.
Click Download.
Rename the .json asciicast file and place it in the /asciicasts directory.
On the page, set asciicast: true in the front-matter.
On the page, include the following html where you want the asciicast to appear. Change the src filepath as relevant, and change poster to the time in the asciicast that you want to use as the static image. For other details about customizing the asciicast appearance, see the asciinema README.

<asciinema-player class="asciinema-demo" src="asciicasts/start-a-local-cluster.json" cols="107" speed="2" theme="solarized-dark" poster="npt:0:30" title="Start a Local Cluster"></asciinema-player>

Images

For information about how we use images in our docs, see the Images in our Style Guide.

Feedback Widget

We show "Yes/No" feedback buttons at the bottom of every page by default. To remove these buttons from a page, set feedback: false in the page's front-matter.

Contributing Options

We show "Contribute" options in the top-right of every page by default. To remove these options from a page, set contribute: false in the page's front-matter.

Client-Side Redirects

We use the JekyllRedirectFrom plugin to ensure that multiple URLs resolve to a single page. This is most useful in cases where we change the filename or directory structure of a page.

For example, if v1.0.html page were moved from the root level to releases/v1.0.html, you would add redirect-from: /v1.0.html to the page's front-matter to ensure that https://cockroachlabs.com/docs/v1.0.html gets redirected to https:/cockroachlabs.com/docs/releases/v1.0.html.

If you rename or restructure a versioned page, use a relative link, not an absolute link. For example, if show-transaction.md and show-time-zone.md are merged into show-vars.md for v1.1, use the following redirect_from specification:

redirect_from:
- show-transaction.html
- show-time-zone.html

This ensures that if v1.1 is also the stable or dev version, the corresponding stable or dev redirects will be generated as well.

Sidebar

For each documented version of CockroachDB, a JSON file in the _includes directory defines the pages that appear in the docs sidebar. For example, the sidebar for CockroachDB v1.0 is defined by _includes/sidebar-data-v1.0.json.

If you're adding a page that you think should appear in the sidebar, please mention this in your pull request.

In the JSON file for a version's sidebar, there are three possible fields:

Field	Type	Description
`title`	String	At the top level, this field defines the title for a section of the sidenav, e.g., `Get Started`. Within the `items` field, `title` defines either the title for a subsection or the title for a page, which can be different from the actual page title. See the JSON Example below for more clarity.
`items`	Array of objects	The pages in a section of the sidenav.
`urls`	Array of strings	The URLs for a page in the sidenav, each formatted as `/${VERSION}/<page-name>.html`, e.g., `/${VERSION}/learn-cockroachdb-sql.html`. The first URL is the page to link to. The subsequent URLs are pages that should highlight this title in the sidebar.

JSON Example

This example shows some of the first section of the sidenav, Get Started:

The first title field defines the section title.
The first items field contains multiple objects, each defining pages in the section:
- The first object defines the title and URL for the first page in the section, Install CockroachDB.
- The second object is more complex. It defines a subsection titled Start a Local Cluster. This object contains its own items field, which in turn contains multiple objects, each defining the title and URL for a page.

[
  {
    "title": "Get Started",
    "items": [
      {
        "title": "Install CockroachDB",
        "urls": [
          "/${VERSION}/install-cockroachdb.html"
        ]
      },
      {
        "title": "Start a Local Cluster",
        "items": [
          {
            "title": "From Binary",
            "urls": [
              "/${VERSION}/start-a-local-cluster.html",
              "/${VERSION}/secure-a-cluster.html"
            ]
          },
          {
            "title": "In Docker",
            "urls": [
              "/${VERSION}/start-a-local-cluster-in-docker.html"
            ]
          }
        ]
      },
      ...
  }
]

Style Guide

See Style Guide for more details.

Build and Test the Docs Locally

Once you've installed Jekyll and have a local clone of the docs repository, you can build and test the docs as follows:

From the root directory of your clone, run:
- For standard docs
```
$ make standard
```
- For managed docs
```
$ make managed
```
Point your browser to http://127.0.0.1:4000/docs/ and manually check your changes.
- If the page you want to test isn't listed in the sidebar, just point to it directly, for example, http://127.0.0.1:4000/docs/new-page.html.
- When you make additional changes, Jekyll automatically regenerates the HTML content. No need to stop and re-start Jekyll; just refresh your browser.
Once you're done viewing your changes, use CTRL-C to stop the Jekyll server.
Run automated tests against the Jekyll-generate HTML files to check for problems (broken links, missing alt texts for images, etc.):
```
$ make test
```

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing to CockroachDB Docs

Setup

Get Started

Keep Contributing

Docs Structure

Pages

Page TOC

Auto-Included Content

Version Tags

Allowed Hashes

Asciicasts

Images

Feedback Widget

Contributing Options

Client-Side Redirects

Sidebar

JSON Example

Style Guide

Build and Test the Docs Locally

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to CockroachDB Docs

Setup

Get Started

Keep Contributing

Docs Structure

Pages

Page TOC

Auto-Included Content

Version Tags

Allowed Hashes

Asciicasts

Images

Feedback Widget

Contributing Options

Client-Side Redirects

Sidebar

JSON Example

Style Guide

Build and Test the Docs Locally