beautiful-docs/beautiful-docs

A beautiful way to read documentation

Beautiful docs

Looking for maintainer

Beautiful docs is a documentation viewer based on markdown files.
Documentation manuals can be described in a manifest file using JSON. It can also generate static pages.

Features:

• Markdown syntax (with support for Github Flavored Markdown)
• The output is fully static and can be hosted on Github or S3
• Uses files, no database (store them anywhere, in git for example)
• Automatically generate the table of content
• Very easy to create your custom theme
• Generate static pages alongside your documentation (eg: easily create a presentation website for your project)
• Clean and beautiful default theme with built-in search engine
• Stylesheet for printing
• Supports embedly
• Easy to customize (eg.: for organizations)
• Support for multiple manifests with an index page

Checkout beautifuldocs.com for an example or github for the sources.
You can find a screenshot of the generated doc here.

Install using npm:

npm install beautiful-docs

Manifests

Manifests are not mandatory but they allow to specify custom options for your documentation.
A manifest file contains a JSON object with the following properties:

• title: Title of the manual (optional, default "Documentation")
• files: An array of files
• links: An array of links, each item must be a tuple of the form: [title, link]
• rootDir: Root directory where files are located. Relative to the manifest pathname
• home: The file to display as the manual homepage (won't be used when computing the TOC)
• css: Filename or URL of a CSS stylesheet that will be included in the page
• category: Category of the manual (used on the index page) (optional, default none)
• maxTocLevel: Maximum number of levels to display in the table of content (default 2)
• makeAssetsRelativeToGithub: set this option to a github repo name (ie. username/reponame) to make assets urls relative to this repo

Files can be absolute URIs, relative to the rootDir option or relative to the manifest file. Example:

{
    "title": "Beautiful Docs",
    "files": ["README.md"]
}

Usage

bfdocs [--option1=value [--option2=value ...]] [/path/to/manifest.json] [/path/to/output/dir]

Available options:

• --help : Display the help information
• --server : Create an HTTP server to access the generated documentation
• --port : The port on which the HTTP server shoud listen
• --watch : Watch files for modifications and reload them automatically
• --theme : Name of bundled theme or path to custom theme
• --title : Title of the index page
• --base-url : Base url of all links
• --manifests-only : Do not treat the last argument as the output dir but also as a manifest
• --index-only : Only generate the index file. The last argument should be the filename of the index
• --version : Display the installed version of beautiful-docs

Default output dir is ./out.
You can specify the path to a directory containing markdown files (*.md) instead of a manifest file

Default theme

The default theme adds the following options to your manifest.json file:

• codeHighlightTheme: The highlightjs theme for code highlighting (http://softwaremaniacs.org/soft/highlight/en/)
• embedly: Activate embedly with the specified api key. Links to embed must be placed alone in a paragraph.
• github: Repository name on github (user/repo) used to display a "Fork me on Github" banner
• googleAnalytics: Google Analytrics Trackind ID. Adds a Google Analytics Tracking code to the generated website
• disqus: Disqus Shortname. Adds a Disqus comment thread to every documentation page

The theme has a search capability. It will generate a search index at compile time and you will be able to search your documentation without the need of a server. Everything is done client side!

You can use the following css classes to style your documentation (suround a block with a div tag):

• note: grey box
• warning: orange box
• tip: green box

Tables will be automatically formatted.

Theming and static pages generation

Beautiful Docs makes it very easy for you to create your own theme. A theme is made of 2 templates:

• _page.html: used to render each file in the files array. Will receive a @content variable with the content of the page
• _manifests.html: used to render the index page of multiple manifests (optional if you don't plan on using this feature)

A few variables are available inside your templates:

• @manifest: the current Manifest object (unless for _manifests.html where it is an array of manifests and the variable is named @manifests)
• @baseUrl: base url
• @title: the title provided through the command line

The Manifest object has some interesting properties:

• options: all the property used in the manifest.json file
• maxTocLevel
• title
• slug: the name of the generated html file without the html extension

Similar to Jekyll, files can have a header enclosed in ---. If such a header is found, the file will be rendered using eco, Beautiful Docs' rendering engine. The header is a YAML blurbs. All properties will be available as variables when rendered.

The special layout property allows your to wrapped the rendered content of the current file inside a layout. It must be a filename relative to the theme path.

Templates have access to the @include(filename) function to include files. The filename must be relative to the current template filename.

All other files in the theme folder are copied over to the output directory. Less and Coffee files will be automatically converted. All files starting with an underscore will be ignored.

Example:

---
layout: _layout.html
---
My custom page for <%= @manifest.title %>

Beautiful Docs comes with 2 themes: default and minimal. Have a look at them in the src/themes folder to learn more about creating your own theme.

Multiple manifests

Beautiful docs can handle multiple manifests at once and generate and index file to easily access each of them.

bfdocs [options] [--manifests-only] /path/to/first/manifest.json /path/to/second/manifest.json /path/to/third/manifest.json [/path/to/output/dir]

If you have more than one manifest and you don't want to specify the output dir, you must use the --manifests-only option.

When multiple manifests are specified, each generated ones will be located in its own subfolder.

You can also generate the index file on its own using --index-only:

bfdocs --index-only /path/to/manifest.json /path/to/manifest.json index.html

Grunt plugin

You can automate the documentation generation using Grunt and the Beautiful Docs task

beautiful-docs's Issues

Image file is sized 0 after running command.

After adding image in form:

![image](assets/img/excel.png)

or

<img src="assets/img/excel.png" />

from directory:
Root
--docs
--assets
---excel.png
--out
--readme.md

is giving error:

An error occured while generating a manifest: Error: ENOENT, open 'E:\www\docs\assets\img\excel.png'

and the image file is resized into 0 kbs

Problem with images

Hi,

I'm trying to generate my docs with images, I have this doc:

My doc:

![Image 1](imgs/path/img1.png)
![Image 2](imgs/path/img2.png)
![Image 3](imgs/path-2/img3.png)

And I get this error:
An error occured while generating a manifest: Error: EEXIST, mkdir 'out/imgs'

I have to execute three times to generate correct paths ... any idea why?

Step-by-step installation

Hi.

First, thank you for the BF Docs.

I'm having trouble installing. I've tried to clone the repository and install via npm. I'm having trouble in options also.

How to install step-by-step.

Thank's!

Support Asciidoc syntax

Please, support asciidoc syntax using asciidoctor-js library

http://asciidoctor.org/docs/install-and-use-asciidoctorjs/

Themes not work

Hi,

I'm trying to use diferent theme to generate my documentation, I try to use minimal theme but not work, I try to make my own themen and not work, I'm using grunt-beautiful-docs tool to generate documentation, I have this options in my gruntfile:

bfdocs: {
      mydoc: {
        options: {
          title: 'My Help',
          manifest: 'docs/manifest.json',
          dest: '<%=pkg.folders.wwwRoot%>help/',
          theme: 'minimal'
        }
      }
    }

anyone can help me with an example of theme?

Thanks

Relative paths

Hi,

it would be great to be able to use relative paths. If --base-url is set, the paths start with a slash. If --base-url is set to an emtpy string, the paths start with true.

Why not just make the paths relative if --base-url is not set? Then I can set it to /if I want the urls to start with a slash.

Then the documentation would be readable without a webserver running (e.g. a part of a download).

–Tim.

Trying to get this up and running

I tried npm install beautiful-docs and it successfully downloaded the files.

I now have both ~/.npm/beautiful-docs and ~/node_modules/beautiful-docs, which doesn't seem right.

When I enter bfdocs --help, I get this error: -bash: bfdocs: command not found

I'm running Mac OS X 10.8.2.

Any idea on what the problem might be?

Pushing to npm via travis.

Since this is a organization 👍 , it would cool to have a automated publishing system which can done using travis-ci, like this:
http://docs.travis-ci.com/user/deployment/npm/

This does have the following advantages:

• Easier to publish new versions.
• Publishing only if tests work.
• Organization can publish instead of the single owner of npm account.

Example configuration from another project:
https://github.com/einigeln/einigeln.js/blob/master/.travis.yml

Files must be defined when manifest is used?

It seems that files has to defined if manifest file is used. This is not documented and feels counterintuitive as running bfdocs without manifest generates output for *.md's in current directory, but use of manifest requires defining files explicitly?

Also: are wildcards supported in paths? (should be documented)

[resolved] Change all < > in code as &lt;

When typing HTML code in markdown instead of markdown text it is normally rendered but code element is not replacing < > with &lt ; and &gt ;

It would be a nice thing as enhancement - two columns with very short code in one row are really nice thing - the only way to achieve that is manully write i.e. :

<div class="col-xs-6 col-sm-6 col-md-6 col-lg-6">
<h5>HTML</h5>
    <pre><code class="html">

    &lt;meta name="robots" content="noindex,nofollow"/&gt;

    </code></pre>
</div>
</div>

Edit:
I see that github markdown with tripple back-apostrophe is doing what I want...

<div class="col-xs-6 col-sm-6 col-md-6 col-lg-6">
<h5>HTML</h5>
<pre>
` ` `
<meta name="robots" content="noindex,nofollow" /> 
` ` `
</pre>
</div>

Style files compiling to [object Object]

A fresh install after npm install

I run bfdocs --watch manifest.json

It works, but no styles are applied. When I look into my css files:

reset.css
[object Object]

I tried reinstalling less on npm but didn't worked.

md images from internet not working

This is because it automatically converts URL's to links.

![image](http://picdrop.t3lab.com/neZVhXDbDk.png)

is translated to

![image](<a href="http://picdrop.t3lab.com/neZVhXDbDk.png.png">http://picdrop.t3lab.com/neZVhXDbDk.png.png</a> =600x)

Tried to find a fix but I'm too unknown with coffee and javascript. Sorry. Nice project!

beautiful-docs installation problem

I am trying to install bfdocs from the master source.
after npm install -g, when i execute command bfdocs, i am getting following error:

module.js:338
    throw err;
          ^
Error: Cannot find module '../lib/command.js'
    at Function.Module._resolveFilename (module.js:336:15)
    at Function.Module._load (module.js:278:25)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at Object.<anonymous> (/usr/local/lib/node_modules/beautiful-docs/bin/bfdocs:2:1)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)

any idea about this problem?

Titles only showing a dot

running from within the directory

bfdocs  --templates-dir='templates/lingewoud/' --title="Documentation"

beautifuldocs.com down?

As described here: https://github.com/beautiful-docs/beautiful-docs

beautifuldocs.com appears to be down, or URL changed?

Slugs and anchors don't match

For the TOC generation, the slugs and anchors that get generated don't match when there is semantic versioning or single quotes in the text.

The fragment used for the TOC drops the decimal point or quote.
The content id replaces each decimal point and quote with a dash.

manifest.json

{
    "files": [
        "whatsnew.md"
    ]
}

whatsnew.md

# What's New
## Version 5.6
## Version 5.5

and the results for the sidebar and content divs:

<div id="sidebar">
  <nav id="toc">
    <ol>
      <li>
        <a href="whatsnew.html#whats-new">What's New</a>
        <ol>
          <li><a href="whatsnew.html#version-56">Version 5.6</a></li>
          <li><a href="whatsnew.html#version-55">Version 5.5</a></li>
        </ol>  
      </li>
    </ol>
  </nav>
</div>

<div id="content">
  <h1 id="what-s-new">What&#39;s New</h1>
  <h2 id="version-5-6">Version 5.6</h2>
  <h2 id="version-5-5">Version 5.5</h2>
</div>

Hash in code blocks breaks output

With files as in https://gist.github.com/phadej/9012293 the output is broken. So when code blocks contain header looking hashes, the rendered html is broken:

This is probably caused by same reason as: #33

Generating Docs from a nested directory of markdown

Hello,

Sorry if I'm missing something here, but I can't seem to figure out how to create documentation when my files are in a nested structure.

say I have

general.md
clients/
     client1.md
     client2.md

Is there a nice way that beautiful docs handles this?

Bugfixes and new Version Tag

This is very promising tool and library, that seems to have compelled in progress.

The latest version 1.0.3 from 2013 (!) has some flaws that can be fixed. Anybody interested in this besides the author?

Not an issue, a request.

Hi, man.
I love that beautiful-docs, it just makes life easier.
I've got a request for you if you will, to make it even better.

Add an option to choose the toc depth.

Creating php framework, I've got classes.
Let's say I create a ABC class.
I like my documentation to be :

ABC class

examples

first example

second example

twenty-third example

...

So, I've got tons of examples, and of course I would have love them to appear in the toc.
Problem now is that the toc only shows the first two levels, which in this case shows :

ABC class

examples

So the user cannot see examples in the toc.

Certain characters in headings break in-page navigation

Apparently non-alphanumeric characters cause inconsistent slug generation, which can break the in-page navigation. For example, this little piece of markdown:

## Object.method(options, callback)
This does stuff.

Gets converted to this a in the sidebar:

<a href="readme.html#objectmethodoptions-callback">Object.method(options, callback)</a>

But the header in the actual content is this:

<h2 id="object-method-options-callback-">Object.method(options, callback)</h2>

The navbar wants to point at an element with an id of objectmethodoptions-callback, whereas the actual element has an id of object-method-options-callback-.

Jason

P.S. Great work on beautiful docs, this is a great project. :)

Add folder example

Add a folder example with a manifest.json and file markdown thereby that the command line of bfdocs

Should not require coffee to run

jb@jborg-mbp:~ % npm install -g beautiful-docs
...
jb@jborg-mbp:~ % bfdocs 
env: coffee: No such file or directory

Best practice seems to indicate to compile to Javascript before pushing to npm.

support links in headlines

If you're using a link within a headline like

## My headline is [awesome](http://awesome.org)

bfdocs don't recognizes that link but renders it as text <a href="http://a... :(

Add node engine dependency

I don't believe this will run on node 0.6.7 because of, at a minimum, fs.exists(). I don't believe fs.exists() was available until 7.1 possibly?

I ran into this because I run 0.6.14 and 0.8.12 and it wouldn't run under 0.6.14.

& in doc-title is displayed as &amp;

If my doc has an & i the title it show & in the toc

Issue with building lunr indexes on windows

I ran into an issue when creating the index for lunr's search.

Chrome's console would show:
Uncaught SyntaxError: Unexpected token ILLEGAL in lunr-index.js

It's because of the multi-line text within the content.
In lunr-index.js, I can see it's replacing newlines with spaces:

body: "<%= section.markdown.replace(/\n/g, " ").replace(/"/g, '\\"') %>"

But that didn't work on Windows.
I replaced it with:

 body: "<%= section.markdown.replace(/(\r\n|\n|\r)/g, " ").replace(/"/g, '\\"') %>"

and that works for me.

bfdocs server has no method configure

Just started with beautiful docs, ahnd created an example manifest.json as in doc example

bfdocs --server --watch manifest.json

Generating documentation from manifest 'manifest.json'
[]
[]
Starting server on port 8080

/usr/lib/node_modules/beautiful-docs/lib/index.js:77
app.configure(function() {
^
TypeError: Object function (req, res, next) {
app.handle(req, res, next);
} has no method 'configure'
at Object.exports.serveStaticDir (/usr/lib/node_modules/beautiful-docs/lib/index.js:77:9)
at startServer (/usr/lib/node_modules/beautiful-docs/lib/command.js:115:21)
at /usr/lib/node_modules/beautiful-docs/lib/command.js:161:18
at /usr/lib/node_modules/beautiful-docs/lib/generator.js:290:18
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:254:17
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:157:25
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:251:21
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:615:34
at /usr/lib/node_modules/beautiful-docs/lib/generator.js:384:18
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:254:17
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:157:25
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:251:21
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:615:34
at done (/usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:135:19)
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:32:16
at /usr/lib/node_modules/beautiful-docs/lib/generator.js:384:18
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:254:17
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:157:25
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:251:21
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:615:34
at done (/usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:135:19)
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:32:16
at /usr/lib/node_modules/beautiful-docs/lib/generator.js:384:18
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:254:17
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:157:25
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:251:21
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:615:34
at done (/usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:135:19)
at /usr/lib/node_modules/beautiful-docs/node_modules/async/lib/async.js:32:16
at Object.oncomplete (fs.js:107:15)

Mixed Setext and atx headers fail

I use setext style headers for the first 2 levels but bfdocs can't handle them :(
A file with mixed setext and atx style headers don't show up in the toc and the generated html isn't complete (fail.html from this example only contains Headline3 and Headline4)

Example:
manifest.json

{
    "title": "headline levels",
    "files": [
        "fail.md",
        "work.md",
        "kindofwork.md"
    ]
}

fail.md

Headline1
====
paragraph1

Headline2
----
paragraph2

### Headline3 ###
paragraph3

### Headline4 ###
paragraph4

work.md

# Headline1 #
paragraph1

## Headline2 ##
paragraph2

### Headline3 ###
paragraph3

### Headline4 ###
paragraph4

kindofwork.md

Headline1
====
paragraph1

Headline2
----
paragraph2

New less-package version 2.0.0-b2 breaks the documentation CSS styles

After running 'npm update' sub package less was updated to version 2.0.0-b2.
That resulted the content of all compiled css-files is only '[object Object]'.

This was working when less version was '1.7.5'

Versions:
npm: 1.4.14
beautiful-docs: 1.0.3
less: 2.0.0-b2

img markdown

Is there a way to markdown a relative path to the file like

![alt text](/pathto/file/img/myimg.png)

I'm getting ENOENT unless I specify the absolute path to the file.

Thanks

Express 4.x breaks bfdocs --server

After NPM installing bfdocs, the --server option exits with an error:

Starting server on port 8080

/home/freaknl/.local/share/npm/lib/node_modules/beautiful-docs/lib/index.js:77
    app.configure(function() {
        ^
TypeError: Object function (req, res, next) {
    app.handle(req, res, next);
  } has no method 'configure'
  at Object.exports.serveStaticDir (/home/freaknl/.local/share/npm/lib/node_modules/beautiful-docs/lib/index.js:77:9)
  at startServer (/home/freaknl/.local/share/npm/lib/node_modules/beautiful-docs/lib/command.js:115:21)

The cause appears to be the removal of the configure method from express >= 4.

A short term solution would probably mean limiting express to pre-4.x releases in package.json.

Multiple <br></br> is added under headings

Hello,

I've an issue where after heading there's alot of <br></br> added into code...but there's nothing like that in MD file.

## CSV Data Structure

<table class="table table-condensed table-bordered">

and the output in HTML file is:

<h2 id="csv-data-structure">CSV Data Structure</h2>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<br></br>
<table class="table table-condensed table-bordered">

Any idea what could have caused that? It's not happening under every heading, but most of them. The count of br is always other.

The following text is rendering elements multiple times.

Tracking User Sessions -- Android ONLY

To track user sessions and gather basic user data, add the following methods to your Activity's onStart() and onStop() methods. You should put these methods in the Activity where users will enter your app, or in a wrapper Activity that your other Activities inherit, if applicable:

public void onStart() { 
  super.onStart(); 
  Appboy.getInstance(YOUR_ACTIVITY.this).openSession(YOUR_ACTIVITY.this); 
}
public void onStop() { 
  super.onStop(); 
  Appboy.getInstance(YOUR_ACTIVITY.this).closeSession(YOUR_ACTIVITY.this); 
}

Setting User IDs

If you have your own user signup process, you can set user IDs and attributes to enhance your ability to target and segment your user base. You should make the following call to ensure that a user of your app has the same identity in both Appboy and your own application:

Android Implementation

Appboy.getInstance(YOUR_ACTIVITY.this).changeUser(YOUR_USER_ID_STRING);

iOS Implementation

[[Appboy sharedInstance] changeUser:@"YOUR_USER_ID"];

Note: Once you identify a user, you cannot go back to the "anonymous" profile. The transition from anonymous to identified tracking only happens once because the initial anonymous user receives special treatment to allow for preservation of their history. We recommend against changing the user id just because your app has entered a "logged out" state because it separates this device from the user profile and thus you will be unable to target the previously logged out user with re-engagement campaigns. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app's logout process.

Logging User Attributes

Appboy provides methods for assigning attributes for your users. You'll be able to filter and segment your users according to these attributes on the Dashboard.

Android Implementation

To assign attributes to your users, call the getCurrentUser() method on your Appboy instance to get a reference to the current user of your app. Once you have a reference to the current user, you can call methods to set predefined or custom attributes.

For example:

Appboy.getInstance(YOUR_ACTIVITY.this).getCurrentUser().setCustomUserAttribute(YOUR_ATTRIBUTE_KEY_STRING, YOUR_ATTRIBUTE_VALUE);    

Additional examples are available in the Droidboy sample project on Github in the UserDialog.java class

iOS Implementation

A list of the default user attributes that you can set can be seen in the "ABKUser.h" file.

To assign user attributes, you need to set the appropriate field on the shared ABKUser object. For example, to assign the current user's first name to be "Jeff," you would use the following line of code:

[Appboy sharedInstance].user.firstName = @"Jeff";

Tracking Custom Events

You can record custom events in Appboy to learn more about your apps' usage patterns and users and segment your userbase on the Dashboard. The method below will lazily record* a custom event to Appboy:

Android Implementation

Appboy.getInstance(YOUR_ACTIVITY.this).logCustomEvent(YOUR_EVENT_STRING);

iOS Implementation

[[Appboy sharedInstance] logCustomEvent:@"your event name"];

"RESTful API Implementation"

Utilizing and tracking custom events is key to unlocking the full analytical potential of the Appboy dashboard.

It would be simple for a gaming app using our pre-existing filter stack to identify “lost users” who hadn’t opened the app during the past several weeks. However, understanding why those users have been lost is equally important. Perhaps a new level was deemed too frustrating by the end user and it caused them to seek easier distractions on their ride to and from work. Using the Custom Events API to track which levels had been “opened” and “completed’ would allow you to identify those points of user frustration quickly and seamlessly directly within the Appboy dashboard.

“Custom Events” can be submitted directly to Appboy using a RESTful API. You can use the API to log custom events taken by your users from applications that do not (or cannot) integrate one of the Appboy mobile SDKs.

Note: You should use a user identifier that you set using the changeUser function in the Mobile SDK. In order to correctly associate app Users with events submitted via web service, you must ensure that your App users are assigned the same external ID in both the Appboy SDK and the Custom Events API. Note that if a user does not exist with the identifier that you supply, we will create a new one.

API requests must also specify an App API key. Your App's API key can be found on the App Settings page of the Dashboard.

API Specification

Custom Events API call implementation:

POST https://dev.appboy.com/events/v1/track
Content-Type: application/json
{
  api_key: "YOUR APP'S API KEY",
  events: [
    {
      user_id: "123", # Your user's ID; see [AppboySession setUserId]
      name: "event_name", # The name of your event, e.g., "watched_video" or "beat_level_1"
      time: 1361226454 # Optional unix timestamp, defaults to the current time
    }
  ]
}

The Server will return the following response:

HTTP Code 201
{
  success: true, # Whether or not the POST succeeded
  processed: 1, # The number processed in the request
  error: "If success is false, this will be a description of the error"
}

Limits

• You can post up to 50 events per request
• You can post up to 2,000 requests per hour. If you need a higher rate limit, please contact us at [email protected]

Hooks for Additional Events

iOS

Recording In-App Purchases

This call could allow you to segment your users on the Dashboard by their true lifetime value.

To use this feature, add this method call after a successful purchase in your app:

[[Appboy sharedInstance] logPurchase:@"your product ID" priceInCents:99]; // price is in cents (an integer)

This will lazily record* the purchase of a "productId" that costs "priceInCents" cents to the Appboy servers.

Recording Social Network Shares

This call could help you to identify your most loyal or influential users.

To record social network shares, add this method after a successful share action in your app:

[[Appboy sharedInstance] logSocialShare:ABKSocialNetworkFacebook]; // or ABKSocialNetworkTwitter

Android

A complete list of calls can be found in the javadocs HERE

Best Practices

Don’t over segment your tracking.

• Being more generic will help you target more users and draw more useful divisions between user segments.
  • For example, rather than capturing a separate event for watching each of 50 different movies, it would be more effective to capture simply watching a movie as an event.
  • If you over segment your user data, your findings will lose statistical significance and won’t guide the development of your app and marketing initiatives as effectively.
  • If you wanted to track “watched_a_movie” as a Custom event then call the API to track “watched_braveheart” you could do that but there are significant drawbacks.
    • The additional API calls will slow down your code.
    • This will slow down your Dashboard performance.
    • You will “miss the forest for the trees” when evaluating user-trend data.
  • In Summary: You should generally capture generic events (“watched_video” or “read_article”) instead of highly specific events such as (“watched_gundam_style” or “read_article_10_lunch_spots_NYC”)

Do not programmatically create event names

• Events should be tied directly to your marketing and conversion goals.
  • If you’re constantly creating new event names it is going to be impossible to meaningfully segment your users. You are going to run into the same (re: likely worse) over-segmentation problems described above.
    • Additionally, programmatic custom events run a risk of containing more than 255 characters.
      • See problem with “255 character” custom events below
    • Solution/Constraints: Do not prefix your custom event names with a "$" sign (e.g., "$viewed", "$opened").

Custom Event Limitations

• All custom events 255 characters or longer will be truncated.
  • Ideally, these should be as short as possible to improve network/battery performance for your app. If possible limit them to 50 characters.
• Quotation marks must be removed
• Leading and trailing whitespace must be removed
• Non-whitespace characters must be converted into spaces
• Integer values are 64 bit.
• Decimals have 15 decimal digits by default.
• Phone numbers set will have all non-digits stripped so if you send in "[phone]" we'll condense to "2144507900"
• Leading and trailing whitespace, newlines, tabs and double-quote characters will be removed.
• $ should not be used as a prefix for any custom events.
• The following keys are RESERVED and should not be used in iOS or Android.
  • email
  • facebook
  • twitter
  • first_name
  • last_name
  • dob
  • external_id
  • country
  • home_city
  • bio
  • gender
  • phone
  • email_suscribe.

Not following ANY of these constraints will lead to inconsistent tracker behavior.

--title option and --base-url option don't work!

I tried --title option and --base-url option,
but none of them succeeded.

Here is what I used for title option.

/Users/me/node_modules/beautiful-docs/bin/bfdocs --title "Boo" "/Volumes/Macintosh HD 2/web/projets/me/web/userdoc/source/manifest.json" "/Volumes/Macintosh HD 2/web/projets/me/web/userdoc/html"

path.exists is now called fs.exists.

fs.js:524
return binding.stat(pathModule._makeLong(path));
^
Error: ENOENT, no such file or directory 'Boo'
at Object.fs.statSync (fs.js:524:18)
at loadManifests (/Users/me/node_modules/beautiful-docs/bin/bfdocs:178:14)
at /Users/me/node_modules/beautiful-docs/bin/bfdocs:201:16
at Object.fs.exists as oncomplete

css and <a> href path

Is there a way to change the default path of the css style sheets and links with [options] or manifest file? So instead of default href="/css/reset.css" you'll get href="newpath/newsource/css/reset.css" and href="newpath/newsource/readme.html#manifests" etc

support for github links

If you link an image in your github README file you'd so s.th. like

![Great Image(myProject/raw/master/image.png)

But if you generate the docs you need the link without myProject/raw/master/. Maybe we should just remove that part if an option like --raplaceGithubLinks is activated?

Breaking dependencies

As detailed in other issues there are a few dependencies whose newer versions cause problems. I got around this by changing the project's dependencies to the following. Basically I changed each dependency from >= to major.minor.x.

"dependencies": {
"coffee-script": "1.6.x",
"eco": "1.0.x",
"express": "3.3.x",
"less": "1.4.x",
"marked": "0.2.x",
"underscore": "1.5.x",
"async": "0.2.x",
"string": "1.5.x",
"js-yaml": "2.1.x"
},

Error - Cannot read property 'options' of undefined

I've got this error when using manifest with multiple files. However, if we only use single file in the files array, it is working.

Below is the manifest.json used:

{
  "title": "User Guide",
  "files": [ "Introduction.md", "GetStarted.md", "Common.md", "Tasks.md" ]
}

and will generate the error below:

usr/local/lib/node_modules/beautiful-docs/lib/manifest.js:82
            if (!this.manifest.options.makeAssetsRelativeToGithub) {

FeatureReq. --input-dir=/path

An option to tell where all .md files are would be handy.

Simple quote (') are HTML escaped from titles in the left side menu

Here is an example:

We have this markdown file which is compiled by beautifuldocs and integrated in a menu:
https://github.com/ezpaarse-project/ezpaarse/blob/353e66f6d0d03be3689a4551069a2cd896c7da69/README.md#tester-linstallation

The source code is (notice the simple quote in the title):

And the result after a beautifuldocs compilation is:

It should display a nice simple quote.