flatdoc

Flatdoc
=======

Flatdoc is a small JavaScript file that fetches Markdown files and renders them
as full pages. Essentially, it's the easiest
way to make open source documentation from Readme files.

* No server-side components
* No build process needed
* Deployable via GitHub Pages
* Can fetch GitHub Readme files
* Gorgeous default theme (and it's responsive)
* Just create an HTML file and deploy!

Current version: [v/0.8.6][dist]


Getting started
---------------

Create a file based on the template, which has a bare DOM, link to the
scripts, and a link to a theme. It will look something like this (not exact).
For GitHub projects, simply place this file in your [GitHub pages] branch and
you're all good to go.

In short: just download this file and upload it somewhere.

The main JS and CSS files are also available in [npm] and [bower].

[Download template >][template]

`` html

















`

[bower]: http://bower.io/search/?q=flatdoc
[npm]: https://www.npmjs.org/package/flatdoc

$3

To fetch a Github Repository's readme file, use the Flatdoc.github fetcher.
This will fetch the Readme file of the repository's default branch.

` javascript
Flatdoc.run({
fetcher: Flatdoc.github('USER/REPO')
});
`

You may also fetch another file other than the Readme file, just specify it as
the 2nd parameter.

` javascript
Flatdoc.run({
fetcher: Flatdoc.github('USER/REPO', 'Changelog.md')
});
`

After you've done this, you probably want to deploy it via [GitHub Pages].

[GitHub Pages guide >][GitHub Pages]

$3

You may also fetch a file. In this example, this fetches the file Readme.md in
the same folder as the HTML file.

` javascript
Flatdoc.run({
fetcher: Flatdoc.file('Readme.md')
});
`

You may actually supply any URL here. It will be fetched via AJAX. This is
useful for local testing.

` javascript
Flatdoc.run({
fetcher: Flatdoc.file('http://yoursite.com/Readme.md')
});
`

How it works
------------

Flatdoc is a hosted .js file (along with a theme and its assets) that you can
add into any page hosted anywhere.

#### All client-side

There are no build scripts or 3rd-party services involved. Everything is done in
the browser. Worried about performance? Oh, It's pretty fast.

Flatdoc utilizes the [GitHub API] to fetch your project's Readme files. You may
also configure it to fetch any arbitrary URL via AJAX.

#### Lightning-fast parsing

Next, it uses [marked], an extremely fast Markdown parser that has support for
GitHub flavored Markdown.

Flatdoc then simply renders menu and content DOM elements to your HTML
document. Flatdoc also comes with a default theme to style your page for you, or
you may opt to create your own styles.

Markdown extras
---------------

Flatdoc offers a few harmless, unobtrusive extras that come in handy in building
documentation sites.

#### Code highlighting

You can use Markdown code fences to make syntax-highlighted text. Simply
surround your text with three backticks. This works in GitHub as well.
See [GitHub Syntax Highlighting][fences] for more info.

` html
Hola, mundo
`

#### Blockquotes

Blockquotes show up as side figures. This is useful for providing side
information or non-code examples.

> Blockquotes are blocks that begin with >.

#### Smart quotes

Single quotes, double quotes, and double-hyphens are automatically replaced to
their typographically-accurate equivalent. This, of course, does not apply to
and

 blocks to leave code alone.
> "From a certain point onward there is no longer any turning back. That is the
> point that must be reached."  
> --Franz Kafka
#### Buttons
If your link text has a > at the end (for instance: Continue >), they show
up as buttons.
> [View in GitHub >][project]
Customizing
===========
Basic
-----
$3
For the default theme (theme-white), You can set theme options by adding
classes to the  element. The available options are:
#### big-h3
Makes 3rd-level headings bigger.
` html

`
#### no-literate
Disables "literate" mode, where code appears on the right and content text
appear on the left.
` html

`
#### large-brief
Makes the opening paragraph large.
` html

`
$3
You have full control over the HTML file, just add markup wherever you see fit.
As long as you leave role='flatdoc-content' and role='flatdoc-menu' empty as
they are, you'll be fine.
Here are some ideas to get you started.
 * Add a CSS file to make your own CSS adjustments.
 * Add a 'Tweet' button on top.
 * Add Google Analytics.
 * Use CSS to style the IDs in menus (#acknowledgements + p).
$3
Flatdoc emits the events flatdoc:loading and flatdoc:ready to help you make
custom behavior when the document loads.
` js
$(document).on('flatdoc:ready', function() {
  // I don't like this section to appear
  $("#acknowledgements").remove();
});
`
Full customization
------------------
You don't have to be restricted to the given theme. Flatdoc is just really one
.js file that expects 2 HTML elements (for menu and content). Start with
the blank template and customize as you see fit.
[Get blank template >][template]
` html

  
    
    
    
    
  
  
    

    

  

``
Misc
====
Inspirations
------------
The following projects have inspired Flatdoc.
 * [Backbone.js] - Jeremy's projects have always adopted this "one page
 documentation" approach which I really love.
 * [Docco] - Jeremy's Docco introduced me to the world of literate programming,
 and side-by-side documentation in general.
 * [Stripe] - Flatdoc took inspiration on the look of their API documentation.
 * [DocumentUp] - This service has the same idea but does a hosted readme 
 parsing approach.
Attributions
------------
Photo taken from Flickr,
licensed under Creative Commons.
Acknowledgements
----------------
© 2013, 2014, Rico Sta. Cruz. Released under the MIT 
License.
Flatdoc is authored and maintained by [Rico Sta. Cruz][rsc] with help from its 
[contributors][c].
 * My website (ricostacruz.com)
 * Github (@rstacruz)
 * Twitter (@rstacruz)
[rsc]: http://ricostacruz.com
[c]:   http://github.com/rstacruz/flatdoc/contributors
[GitHub API]: http://github.com/api
[marked]: https://github.com/chjj/marked
[Backbone.js]: http://backbonejs.org
[dox]: https://github.com/visionmedia/dox
[Stripe]: https://stripe.com/docs/api
[Docco]: http://jashkenas.github.com/docco
[GitHub pages]: https://pages.github.com
[fences]:https://help.github.com/articles/github-flavored-markdown#syntax-highlighting
[DocumentUp]: http://documentup.com
[project]: https://github.com/rstacruz/flatdoc
[template]: https://github.com/rstacruz/flatdoc/raw/gh-pages/templates/template.html
[blank]: https://github.com/rstacruz/flatdoc/raw/gh-pages/templates/blank.html
[dist]: https://github.com/rstacruz/flatdoc/tree/gh-pages/v/0.8.6