Contributing > Documentation




These instructions presume you have setup the build environment.

Docs, Topics, and Sections

First off, docs are declared as a collection in jekyll’s _config.yml so that jekyll will process any markdown in the _docs folder when building the site.

Docs are then organized into topics and sections. topics are subfolders in the _docs folder and each section should have a front matter tag topic: .... The folder structure is

_docs
|__ aws 
|__ backend
|__ contributing
|__ database
|__ frontend
|__ instances
|__ monitoring
|__ security
|__ usage

each topic folder has an index.md file such as

---
layout: docs
title: Overview
topic: aws
section: index
---
...

Note the following front matter definitions:

  • topic defines what “topic” this section falls under
  • section is a short name for this section

Topics and sections are ordered as they appear in the file _data/docorder.yml.

The file /_includes/docsidebar.html contains the html and liquid markup for creating the dynamic sidebar contents for the documentation. If the markdown section files in docs have reasonable topic and order definitions, this sidebar will get built correctly. You shouldn’t need to edit this in any way to get the sidebar built correctly. Where the files are inside _docs actually doesn’t matter for site building, but does make a different for us humans.


Editing a Section


Say you need to edit an existing section. This is fairly easy, and only involves changing markdown in the section file. Try to leave the documentation’s front matter sections alone whenever you can.

You should either clone cfsite into some folder

$ git clone git@bitbucket.org:circleresearch/cfsite.git folder

or, from that folder if it already exists, pull the latest version of master

$ git pull origin master

(NOTE: you shouldn’t be able to push to master). Then create your own branch

$ git checkout -b my-branch

and start editing whatever documentation sections you like.

Two recommendations: First, use the local development server while editing to get somewhere close to a finished product before uploading. Second, if you are collaborating, let your team members know what sections you are working on.

When you are done, you should push your branch

$ git push -u origin my-branch

and then visit bitbucket to create a pull request. There is a tutorial here if you haven’t done this before.


Adding a Section


Adding a section is harder, as it involves changes to how sections are ordered within topics. What you need to do is create a new file with the right frontmatter, add your chosen section key from the front matter to the right (topic) section of _data/docorder.yml in the right order, and then edit that document to your liking.

Let’s consider an example. Suppose we wanted to add a section “More about cfserver” to the backend topic. We might create a file _docs/backend/morecfserver.md with front matter

---
layout: docs
title: More About cfserver
topic: backend
section: morecfserver
---

and then modify _data/docorder.yml to be

...
- name: backend
  sections: 
  - index
  - cfserver
  - morecfserver
  - authrbac
  - install
  - config
...

Then we can edit the file _docs/backend/morecfserver.md as we like. The docs sidebar navigation will automatically update because we updated _data/docorder.yml.


Adding a Topic


Adding topics is probably to be avoided. But if you want to,

Was this page useful?   or