Anatomy of the Docs

Directory Structure & Contents

The docs repo isn't terribly complicated but it has a lot of material in it and at first glance it may not be clear what does what. The tables below summarize what everything is.

Miscellaneous Files

File or directory	Function
Gemfile	The list of Rubygems used by all of the Ruby bits that make the docs tick
config.ru, config.rb, service.ru	Some configuration and other bits for the Ruby Rack server that runs the docs locally. You probably won't need to touch this.
deploy-service.rb, deploy.rb	The deployment scripts used to push the docs to S3.
README.md	The README that you see on the main GitHub page.
LICENSE.md	The text of the Creative Commons license used by the docs

Directories

File or directory	Function
build	The contents of this folder are ephemeral. Basically a bunch of generated content for when you run the docs locally. Don't worry about this.
data	This holds the versions.yml that defines the docs' various versions (more on this below) as well as two files used to power the downloads page. Don't ever modify the downloads_gen.yml file, as it's auto-generated. Modify the downloads_defaults.yml only in consultation with a Basho Release Engineer.
lib	This holds most of the Ruby files that power the docs.
source	This is the real meat of the docs. The contents of this directory are detailed in the table below.

Files in the source Directory

File or directory	Function
404.erb	The ERB template for the 404 Not Found page that pops if you try to navigate to a URL for a page that doesn't exist
crossdomain.xml	The cross-domain policy file for HTTP streaming. Leave this alone.
favicon.io	Self explanatory
humans.txt	Self explanatory
keywords.slim	A template that may not be in use.
redirect.erb	The ERB template for the "Redirect" page that pops up if you go to an old URL that is no longer valid but has a redirect associated with it.
robots.txt	Self explanatory
sitemap.xml.builder	Self explanatory.

Directories in the source Directory

File or directory	Function
css	The CSS that powers the site. There's a lot in there, but most of the bits that are specific to the site (and not just boilerplate) are in common.css.scss.
data	Any and all non-image static files that are used in the docs.
fonts	The fonts used by the site.
images	The image files used in various places in the docs.
js	The JavaScript bits that power things like the Bitcask calculator, the versions bar, and other things.
languages	This is where the actual docs are housed. Right now there's only one language, English, which is housed in the en folder. 90+% of everything you do will be here.
layouts	The SLIM layouts for aspects of each page. Modify these carefully and only when necessary.

Doc Metadata

Each document in the docs, i.e. each actual Markdown file, has metadata at the top that specifies what versions the doc applies to and a bunch of other stuff. The table below explains what each bit means:

Key	Value	Necessary?
title	The name of the page in big letters at the top. The title is used for things like the global nav (more on that below) and for the wiki link system.	yes
project	Two options here: riak and riakcs	yes
version	The versions of the docs to which this page applies. It's very important to get this right.	yes
document	The type of document, i.e. tutorial vs. reference vs. whatever else.	yes
audience	The options are beginner, intermediate, or advanced. Not currently required.	no
keywords	Not currently required.	no
moved	See the Redirects section below
toc	Set to true if you want a table of contents to appear at the top of the page. More in the Table of Contents section below. true by default.	no