Bonfire guides guidelines (outdated)

1 Markdown

These guides are formatted using the Markdown Extra syntax, which is a plain-text format that extends the Markdown Syntax. You can find comprehensive documentation at the above links, and can even grab a cheat sheet.

2 Introduction

Each section should have an introduction that briefly describes what this guide covers and what they should know by the end of the guide.

3 Titles

Use <h2> tags for chapters, and <h3> tags for sections. Each Chapter and section should be prefaced by the number or section number of the content.

Capitalize all words except for internal articles, prepositions, conjunctions, and forms of the verb to be:

## 1 When are Users Saved?

### 1.1 Chapter Secton

4 Prose Guidelines

The guides and the API docs should share similar writing styles. Please refer to the API Documentation Guidelines for further information.

5 File Structure

When writing new guides, the guide file should be in the main 'pages' directory, and not in a subfolder.

The file itself consists of four parts: the meta information, the main content, the info section and the sidebar.

5.1 Meta Information

The meta information is the first part of the file and currently only contains the page title. The block is enclosed by a line just above and just below that contains only three dashes:

---
title: My Page Title
---

5.2 Main Content

The main chunk of your file will be made up of the body content, that appears in the left-hand column of the page. It can consist of any Markdown formatted documentation that your guide needs. Be sure to include plenty of examples so that what you're trying to describe is clear.

5.3 Info Section

Following your main content is the introductory section. This contains the motivational text that appears in the Introduction (see above). This should be separated from the main content by a single line:

---introtext---

## Page Title

Introductory text goes here.

5.4 Sidebar

Next are the links that make up the sidebar. Similar to the Introductory text, this section is separated from the introductory text by another single line:

---sidebar--

### Chapters

1. [Section 1](#section1)
  * [SubSection 1](#subsection1) 

You an examine any of the existing guides for examples, if needed.

6 Generating the Guides

You can generate the guides on your own machine if you want to preview what your changes will look like. This can be done either dynamically or by creating the static files. Note that any files you generate will not be included in master, but are for your own use only.

6.1 PieCrust

Bonfire Guides are transformed from raw Markdown files into HTML by the PieCrust static website generator. It provides a simple means to 'bake' the files into standalone html files, while wrapping it in a template for consistency. Note that it does require PHP 5.3 to be installed.

6.2 Static Generation

To generate static versions of the guides for your own use you should navigate to the docs/ folder and type the following at the command line:

$ ./_piecrust/chef.php bake -f --fileurls -o ./guides ./guides_src/

This will force a rebuild of the guides into the ./guides folder.