See on github

Usage

Elements

 

Usage

Bibliosoph is customizable. You can add a left menu (like on this site) if you plan on having many pages, you can add a page navigation if your page is long. Plus, the layout will update automatically based on what you define in the config.json. Let's explore your options.

 

Edit the site info

Just open the config.json file and start editing it to your needs.

name
Used for the logo and page <title> tag
repository (optional)
Creates a button "See the code" in the header pointing to the url provided
download (optional)
Creates a button "Download" in the header pointing to your download
analytics_id (optional)
The Google Analytics UA code. If you use something else than Google Analytics
domain (optional)
Which domain is Google Analytics setup for
credits
Wether or not you want to show us some love and add a discrete "Powered by Bibliosoph" link
menu (optional)
If you want plan on having multiple page on your site, you can define a menu by setting the menu config and passing it an array of objects. Each object takes the following attributes:
  • title: The title of the menu item
  • url: The url of the menu item
  • class: The css class of the menu item (required)
  • children: An array of objects very much like the menu one. This will cause a sliding menu with the children items to open when you mouseover the menu item.

If you used Yeoman to install Bibliosoph, the config.json is already populated based on the answer you gave to the generator.

Exemple of a config.json

{
    "site": {
        "name"          : "Bibliosoph",
        "domain"        : "pilla.rs",
        "analytics_id"  : "UA-41628335-1",
        "repository"    : "http://yourprojectcodeurl.com",
        "download"      : "http://yourprojectdownloadurl.com",
        "credits"       : true,
        "menu"          : [
            {
                "title"     : "Manifesto",
                "url"       : "/manifesto",
                "class"     : "manifesto"
            },
            {
                "title"     : "Components",
                "url"       : "/components",
                "class"     : "components",
                "children"  : [
                    {
                        "title"   : "Component 1",
                        "url"     : "/components/component-1",
                        "class"   : "component-1"
                    }
                ]
            }
        ]
    }
}
 

Add a page

As a convention, each documentation page is contained into a folder inside the views/. For instance the homepage documentation of Bibliosoph sits in views/home/. If you want to create a tutorial page, just add a views/tutorial/ folder.

A documentation folder has *.jade templates files and a menu.json. The *.jade files are sections of the documentation and the menu.json file is there to define in what order you want to include the sections; it is also used to generate the navigation (if you use a layout with a navigation).

Documentation structure

views/
    home/
    |   menu.json
    |   intro.jade
    |   license.jade
    |   ...
    tutorial/
 

Write a section

Just create a file inside the tutorial folder (or whatever you named it) you previouly created. For instance, let's add a intro.jade template.

The title() function let you define a title that will be used in the navigation. This will make more sense when we see what goes in the menu.json.

One column layouts: If you use the one_col or one_col_nav layout, you are free to use whatever html structure you want. Note that jade provide a :markdown filter to write your documentation as Markdown. Bibliosoph use marked to parse Markdown content.

Two columns layouts: If you use the two_col or two_col_nav layout, you have to wrap the left column into a div.left and the right column into a div.right. That way, Bibliosoph can properly style the content.

Bibliosoph documentation structure

- title('Introduction')

div.left
    :markdown
        ## A title
        Some content...

div.right
    :markdown
        ### Another title
        ` ``
        A code block...
        ` ``
 

Define the menu

You have to define a menu.json file even if you don't use a layout with a navigation; otherwise Bibliosoph doesn't know what to load.

The menu.json is an array of objects. Each object represents a group of sections and takes two configurables:

  • title: the title to give to the group.
  • children: an array of the template file names.

Bibliosoph also offers subsections. If you look at the nav, in the children array, replace the file name string by an array with two value, the file name first and secondly an array of the children file names.

An exemple of nesting is given in the Usage group with the usage_addpage. It is also the section you are currently reading in Bibliosoph documentation so you can see on the left navigation how nested items are shown when the section is active.

Bibliosoph Home menu.json

[
    {
        "title": "Introduction",
        "children": [
            "intro",
            "getstarted",
            "changelog",
            "license"
        ]
    },
    {
        "title": "Usage",
        "children": [
            "usage_intro",
            "usage_editsiteinfo",
            ["usage_addpage", [
                "usage_addpage_write",
                "usage_addpage_menu",
                "usage_addpage_route"
            ]],
            "usage_deploy"
        ]
    }
]
 

Define the route

First you need to tell express that there is a new route. Open the routes.js file.

Set the route you want as the first argument of the app.get() function. For the homepage, we have '/'.

Set the view you want as the first argument of the res.render() function. By default, Bibliosoph comes with 4 views:

  • one_col: All the content is displayed into one column
  • one_col_nav: same as one_col, plus an automatically generated navigation.
  • two_col: The content is divided into two columns like the Backbone annoted source.
  • two_col_nav: same as two_col, plus an automatically generated navigation.

folderToHTML is a library that let you pre-render an entire folder into an html partial that is then passed to the view. It has a simple API:

  • render: Takes the directory path as an argument. It like a init function, it must be called first.
  • getMenuHTML: returns the html for the navigation. It is useful only if you use a view that render the navigation.
  • getSectionsHTML: returns the html for files.

Finally, you can pass an active variable to the view. It is only used to know which menu item should be displayed as active. Then, it must match the class you have defined in the config.json for the menu item.

Exemple of a config.json

app.get('/', function (req, res) {

  folderToHTML.render(__dirname+'/views/home/');

  res.render('two_col_nav', {
    title: "Documentation template",
    active: 'home',
    menu: folderToHTML.getMenuHTML(),
    html: folderToHTML.getSectionsHTML()
  })
});
 

Customize the styles

Bibliosoph comes with some handy Elements but you can easily customize them or add your own. The css is written using Stylus and sits in the assets/css folder. Though if you ever want to upgrade Bibliosoph and benefit from new Elements and features, you mustn't edit any of the *.styl files. That way, when you update Bibliosoph, the css can upgrade silently.

But don't worry we got you covered if you want to overwrite the css, there is a assets/css/customize/ folder with a base.styl file in it. You can do whatever you want inside this folder, create new files, import them inside the base.styl...

The base.styl is loaded last in the project, so it lets you overwrite everything.

Add icons to the menu items

Bibliosoph comes with the TWG icon set (optimized for the web). To add an icon to a menu item, add something like this to the assets/css/customize/base.styl file:

.my-menu-item-class span {
  background: url('../images/icons/icon_48.png') no-repeat 0 0;
}

body.left-nav-narrow .my-menu-item-class span {
  background: url('../images/icons/icon_24.png') no-repeat 0 0;
}

The left-nav-narrow class is used by the responsive layout.

 

Deploy

You can deploy your documentation as a node app on your own server or use Heroku, Nodester, Nodejitsu or any other Node.js host.

We use the free plan of Heroku. And to prevent the idling, we use the scheduler to ping our site every 50 minutes.

To get started, follow the comprehensive guide about node on Heroku. Once logged in with the heroku cli, run the following commands:

heroku addons:add scheduler:standard
heroku addons:open scheduler

In the webpage that opens, set the task to no_idle and the frequency to every 10 minutes. The task will ping your site every 10 minutes, preventing it from idling.

 

Elements

Bibliosoph comes with different elements that you can use to improve your documentation.

 

Content blocks

Every section of the documentation is actually wrapped in a <section> tag. So are nested subsections. You are free to structure the content inside them the way you want. Though to make things easy, Bibliosoph comes with predefined structural block level:

  • div.left: creates a block that will be displayed in the left column in the two-column layout
  • div.right: creates a block that will be displayed in the right column in the two-column layout
  • div.full: creates a block that will the full width; the two columns in the two-column layout

The div.right style is little specific. By default, it has huge padding-top so that its content vertically align with the one from the div.left. However, it is not something you always want. To reduce the padding, add the class div.right.thin-padding. To remove it, add the class div.right.no-padding.

Those structural blocks are especially useful for the two-column layout. Though they will display nicely if you change the layout to a one-column one.

Exemple of markup

div.left
    // content for the left column

div.right
    // content for the right column

div.full
    // content to display on the full width available
 

Code blocks

If you use markdown, you can use code block like show on the right.

If you use raw html, just wrap the code block in a <pre><code> block.

Code blocks are highlighted using highlight.js.

Highlight.js automatically detect the language of your code block. If you want to force it, you can define it right after the ``` opening tag. For instance, you can do ```json.

By default Bibliosoph include the basic highlight.js language package. If you have specific needs, replace the js/highlight.js file with a custom build.

Exemple of markup

:markdown
  ```
  // a code block in markdown
  ```
pre
    code
        // a code block in jade
 

Hints and notes

It is sometimes nice to be able to add a tip or hint to your documentation. It help breaks down the text into meaninful visual blocks. Bibliosoph has the following classes:

  • .hint: creates a block that will be displayed in the left column in the two-column layout
  • .note: creates a block that will be displayed in the right column in the two-column layout

Exemple of markup

div.hint
    p This is a hint.

div.note
    p This is a note.

How it renders:

This is a hint.

This is a note.

This is a hint.

This is a note.

 

FAQ

You can create static FAQs by create a dl.faq. If you have many questions or long answers, it is sometimes nice to be able to collapse the answers. Add a .accordion class to turn the FAQ into accordion style.

How it renders:

Is this a question?
That's an answer!
Is this another question?
Yes it is!

Exemple of markup

dl.faq.accordion
    dt Is this a question?
    dd That's an answer!

    dt Is this another question?
    dd Yes it is!
 

REST API

If you need to document a REST API, you can easily create documentations like so:

How it renders:

Get a users

get
/users/:id
Parameter nameValueDescription
id 1 The id of the user to get

Create a user

post
/users
Parameter nameValueDescription
email email@exemple.com The email for the new user
password 12345 The password for the new user

Edit a user

put
/users/:id
Parameter nameValueDescription
id 1 The id of the user to edit
email email@exemple.com The new email for the user to edit
password 12345 The new password for the user to edit

Delete a user

delete
/users/:id
Parameter nameValueDescription
id 1 The id of the user to delete
 

Github embeds

Github files

You can easily embed Github snippets inside your documentation. To do so create a div.github-embed and set some data attributes on it.

  • user: the github user
  • repo: the github repo name
  • path: path to the file in the repo
  • sha: sha of the file (as precedence over path)
  • lang: (optional) the language of the code (used for hilights.js)

Gist

You can also embed gist by copy/pasting the embed code from the gist page.

Exemple of markup

div.right
    div(class="github-embed", data-user="pillars", data-repo="bibliosoph", data-path="package.json")

How it renders:

 

JSFiddle embeds

You can easily embed JSFiddle playgrounds inside your documentation. Add a class jsfiddle to the ifram embed code. Then you can use JSFiddle options like you would normaly do.

Note that you can use inline style if you need but by default, the JSfiddle iframes take 100% of its parent width and 300px height.

Exemple of markup

div.full
    iframe(class="jsfiddle", style="height: 200px", src="http://jsfiddle.net/user/GuxxM/embedded/")

How it renders: