RethinkDB docs

This repository contains all of the documentation available at rethinkdb.com. We use Jekyll to build the site, so documentation is written in Markdown.

Contributions are welcome, so fork the repository, submit a pull request, or open an issue so we can improve the documentation.

Guidelines

YAML front-matter

We use Jekyll to build a static site. Each file starts with a YAML front-matter block, which defines variables used by Jekyll in the build process. The required variables are:

---
layout: documentation                 # The layout we are going to use
title: Introduction to ReQL           # Title of the page
active: docs                          # The active link in the navbar at the top of the page
docs_active: introduction-to-reql     # The active link in the documentation index on the right
permalink: docs/introduction-to-reql/ # URL of the page
---

Markdown parser

The site use Redcarpet to parse the Markdown files, so make sure that you use the appropriate syntax. See this handy guide to get started with Markdown. Use Markdown as much as you can. Use HTML markup only if needed.

Consistency for multi-version docs

Some documentation pages have multiple versions for different languages, client drivers, platforms, etc. All updates should be reflected in each version of the page.

For example, if you add a recipe to the Cookbook, you will have to add it to the JavaScript, Python and Ruby versions of the recipe. If you aren't familiar with one of the languages, we'll be more than happy to help you add all the versions.

Architecture

API docs

All the API files are in /api. Each language has its own directory, which means that ReQL command changes require updating three different files. The file index.md contains a short description of every command.

Each command has a dedicated Markdown file for each language. A YAML header is used in each file for our Jekyll build system, and has to contain:

---
# The layout of the document
layout: api-command
# The language, valid values are JavaScript, Python, Ruby
language: JavaScript
# The permalink
permalink: api/javascript/add_listener/
# The name of the command (used in the title)
command: addListener
# This method is not defined in a language, in this case, JavaScript -- (valid keys are js, py, rb) -- optional
js: false
# Defines the input and output of the command
io: [...]
# Set of related commands
related_commands:
    - <name>: <url_from_parent>
    - <name>: <url_from_parent>
---

Custom Jekyll tags

faqsection: defines a FAQ section (e.g. the Cookbook), and creates links to jump to the relevant entry.

{% faqsection %} <body> {% endfaqsection %}

apisection: defines an API section as seen On the API index.

{% apisection %} <body> {% endapisection %}

apibody: defines the method signature of a ReQL command

{% apibody %} <body> {% endapibody %}

infobox: produces an info box -- the info version of the infobox produces a blue box

{% infobox info %} <content> {% endinfobox %}

Contribute

While the RethinkDB team works hard to provide high quality documentation, you may encounter errors or missing information.

Feel free to fork the repository, commit changes and open a pull request!

License

This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

chrisvariety / docs