documentation-editor

Documentation Editor

This is the mountable Rails application providing the documentation editor of algolia.com/doc.

The goal of this project is to provide an easy & frictionless way to edit an online tech documentation. The sweet spot of this editor is to be able to generate pages containing multiple snippets of highlighted code & conditional sections (which wasn't really available in any other CMS we considered). It also includes a nice image uploader storing the image to Amazon S3, a simple table editor and an automatic table of content generator.

Features

• Widgets
  • Text: full markdown support
  • Callout: info/warning/danger
  • Tables: customizable number of columns & rows
  • Code: code snippet with highlighting
  • Conditions: ability to display some sections based on some query parameters
  • Image: image uploader + ability to store on S3
  • Buttons: labeled buttons
• Caching
• Automatic TOC generation (anchors are automatically generated on each title)
• Raw edition mode
• Administration restricted access
• Undo
• Versionning
• Diff

Installation

Dependencies

Your project needs to depend on the following libraries:

• Angular.js,
• ng-file-upload.js,
• Bootstrap 3,
• and Fontawesome 4.

This project depends on:

• rails (> 4.0),
• haml-rails,
• sass-rails,
• kramdown,
• highlight,
• simple_form,
• sass-rails,
• and paperclip.

Setup

To use it in your own Rails project, do the following steps:

• Add the documentation_editor gem to your Genfile

• Mount the provided routes adding the following Engine to your config/routes.rb file:

Rails.application.routes.draw do
  #
  # [ ... ]
  #
  mount DocumentationEditor::Engine => "/doc"
end

• Add the following dependency in your application.js:

// Make sure you've required `jquery`, `angular` and `ng-file-upload` before
//
//= require documentation_editor/pages

• Add the following dependency in your application.css:

/*
* Make sure you've required `bootstrap` before
*
*= require documentation_editor/pages
*/

• Run the underlying migrations:

$ rake db:migrate

• Go to /doc/admin to create your first page

Configuration

Create a config/initializers/documentation_editor.rb file to configure the editor:

# to use a custom layout
DocumentationEditor::Config.layout = 'my_custom_layout'

# to protect the access to the edition pages to admin
DocumentationEditor::Config.is_admin = :method_checking_if_admin?

# to configure a before_filter to add on the 'show' & 'preview' actions
DocumentationEditor::Config.before_filter = :my_before_filter

# to use custom options for paperclip
DocumentationEditor::Config.paperclip_options = {
  storage: 's3',
  s3_credentials: { bucket: 'xxx', access_key_id: 'xxx', secret_access_key: 'xxx' },
  s3_host_alias: 'xxxxxxxxxx.cloudfront.net',
  url: ':s3_alias_url',
  path: ':attachment/:id/:style.:extension'
}

# to wrap your h1 sections with `<section>` tags
DocumentationEditor::Config.wrap_h1_with_sections = true

# to lower all title levels by 1 (h1 -> h2, h2 -> h3, ..)
DocumentationEditor::Config.lower_title_levels = true

Extensions

Language conditions

You can force a page to only display a specific language. To force the language of a page, you need to set the language query parameter. We recommend inlining those parameters directly from your routes.rb file:

Rails.application.routes.draw do
  get '/doc/ruby', :controller => 'pages', :action => 'show', slug: 'guide', language: 'ruby'
  mount DocumentationEditor::Engine => "/doc"
end

Use [[LANGUAGE]] ... [[/LANGUAGE]] to only display a piece of text if this is the current language. For instance:

[[ruby]]This will only be displayed if languag=ruby[[/ruby]] but this will be always displayed.

If you want a tab of your code snippet to be displayed whatever the language, you can use the special * language name. For instance, this JavaScript snippet will be displayed whatever the language specified:

Variables

Rails.application.routes.draw do
  get '/doc/ruby', :controller => 'pages', :action => 'show', slug: 'my_page', variables: { name: 'Foo' }
  mount DocumentationEditor::Engine => "/doc"
end

Use [[variable:VARIABLE]] and specify any variables you want to display their values. For instance:

This is the value of the `name` variable: [[variable:name]].

Section Restriction

Rails.application.routes.draw do
  get '/doc/ruby(/:section)', :controller => 'pages', :action => 'show', slug: 'my_page'
  mount DocumentationEditor::Engine => "/doc"
end

If you're using the wrap_h1_with_sections option you can use the :section param to restrict the rendering to a specific section your page. The TOC will still contain everything. That's something you may want to use for SEO reasons. This must be the last part of your URL.

Usage

Create your first page from the /doc/admin URL.

This is what the previous code generates:

And this is what it looks like once styled:

What the history/diff looks like:

Development

$ bundle install
$ cd test/dummy
$ rake documentation_editor:install:migrations
$ rake db:migrate
$ rails server
$ open http://localhost:3000/doc/admin

Credits

This has originally been inspired by the great readme.io service and adapted to fit Algolia's needs.