documentation-editor 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6865ded279e8812942a89a64c22b9f17d63e8501
+  data.tar.gz: c859360db9e6c0bb4ec201f4a321ae0d93a7c8d5
+SHA512:
+  metadata.gz: f2cae69accca7804d12a1b48413d69aa1fc1d86e3baf908f61fc3d414e48b206e599ced9236b8f8350c66da05cbdbc03203fa2fc240006e7e010bb6913bff69c
+  data.tar.gz: 887456febdb9b0a6dba729c1773be3633923495cb647772e02c2754f88ed46c5db384660e511aab20d0966e0448b31c288a9b154466d96ca796f2e3b175b866b

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Algolia
+http://www.algolia.com/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# Documentation Editor
+
+[![Build Status](https://travis-ci.org/algolia/documentation-editor.png?branch=master)](https://travis-ci.org/algolia/documentation-editor) [![Gem Version](https://badge.fury.io/rb/documentaton-editor.png)](http://badge.fury.io/rb/documentation-editor)
+
+This is the mountable Rails application providing the documentation editor of [algolia.com/doc](https://www.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
+ - 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:
+
+```ruby
+Rails.application.routes.draw do
+  #
+  # [ ... ]
+  #
+  mount DocumentationEditor::Engine => "/doc"
+end
+```
+
+ * Add the following dependency in your `application.js`:
+
+```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`:
+
+ ```css
+/*
+ * Make sure you've required `bootstrap` before
+ *
+ *= require documentation_editor/pages
+ */
+ ```
+
+ * Run the underlying migrations:
+
+```sh
+$ 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:
+
+```ruby
+# 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 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
+```
+
+## Markdown 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:
+
+```ruby
+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:
+
+```html
+[[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:
+
+![star](doc/snippet-star.png)
+
+#### Variables
+
+```ruby
+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:
+
+```html
+This is the value of the `name` variable: [[variable:name]].
+```
+
+## Usage
+
+Create your first page from the `/doc/admin` URL.
+
+![Editor](doc/editor.png)
+
+This is what the previous code generates:
+
+![Preview](doc/preview.png)
+
+And this is what it looks like once styled:
+
+![Final](doc/final.png)
+
+What the history/diff looks like:
+
+![History](doc/history.png)
+
+
+## Development
+
+```sh
+$ 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](http://readme.io/) service and adapted to fit [Algolia](https://www.algolia.com)'s needs.

data/Rakefile

@@ -0,0 +1,37 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'DocumentationEditor'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/documentation_editor/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/javascripts/documentation_editor/pages.js

@@ -0,0 +1,521 @@
+angular.module('documentationEditorApp', ['ngFileUpload'])
+  .config(['$locationProvider', function($locationProvider) {
+    $locationProvider.html5Mode({ enabled: true, requireBase: false, rewriteLinks: false });
+  }])
+  .controller('EditorController', ['$scope', '$http', '$window', '$location', function($scope, $http, $window, $location) {
+    $scope.sections = [];
+    $scope.undoRedo = [];
+    $scope.id = 0;
+    $scope.slug = '';
+    $scope.source = '';
+
+    $scope.nextID = 0;
+    function getNextID() {
+      return $scope.nextID++;
+    }
+
+    function parse(source) {
+      var lines = source.split("\n");
+      var currentBlock = null, blockContent = '';
+      var sections = [];
+      for (var i = 0; i < lines.length; ++i) {
+        var line = lines[i];
+        if (line.indexOf('[block:') === 0) {
+          currentBlock = line.substring(7, line.length - 1);
+        } else if (line.indexOf('[/block]') === 0) {
+          sections.push({
+            id: getNextID(),
+            type: currentBlock,
+            content: JSON.parse(blockContent)
+          });
+          currentBlock = null;
+          blockContent = '';
+        } else if (currentBlock != null) {
+          blockContent = blockContent + line + '\n';
+        } else {
+          if (sections.length > 0 && sections[sections.length - 1].type === 'text') {
+            sections[sections.length - 1].content = (sections[sections.length - 1].content + "\n" + line).replace(/\n{2,}$/, "\n\n");
+          } else if (line) {
+            sections.push({
+              id: getNextID(),
+              type: 'text',
+              content: line
+            });
+          }
+        }
+      }
+      return sections;
+    }
+
+    function serialize(sections) {
+      var data = [];
+      $.each(sections, function(i, section) {
+        if (section.type === 'text') {
+          data.push(section.content + "\n");
+        } else {
+          data.push('[block:' + section.type + ']');
+          data.push(JSON.stringify(section.content));
+          data.push("[/block]\n");
+        }
+      });
+      return data.join("\n");
+    }
+
+    $scope.init = function(id, slug, path) {
+      $scope.id = id;
+      $scope.slug = slug;
+      $scope.path = path;
+
+      $http.get($scope.path + '/admin/' + id).then(function(content) {
+        $scope.source = content.data.source;
+        $scope.sections = parse($scope.source);
+      });
+    };
+
+    $scope.rawView =  false;
+    $scope.toggleView = function($event) {
+      $event.preventDefault();
+      $scope.undoRedo = [];
+      if ($scope.rawView) {
+        $scope.sections = parse(this.source);
+      } else {
+        $scope.source = serialize($scope.sections);
+      }
+      $scope.rawView = !$scope.rawView;
+    };
+
+    $scope.undo = function($event) {
+      $event.preventDefault();
+      if ($scope.undoRedo.length === 0) {
+        return;
+      }
+      var o = $scope.undoRedo.pop();
+      if (o.type === 'addSection') {
+        $scope.sections = $.grep($scope.sections, function(e) { return e.id !== o.data.obj.id });
+      } else if (o.type === 'deleteSection') {
+        $scope.sections = o.data.sections;
+      } else if (o.type === 'deleteLanguage' || o.type === 'addLanguage') {
+        var index = getIndex(o.data.id);
+        var obj = {
+          id: $scope.sections[index].id,
+          type: 'code',
+          content: {
+            codes: o.data.codes
+          }
+        };
+        $scope.sections = [].concat($scope.sections.slice(0, index), [obj], $scope.sections.slice(index + 1));
+      } else if (o.type === 'deleteColumn' || o.type === 'addColumn' || o.type === 'addRow' || o.type === 'deleteRow') {
+        var index = getIndex(o.data.id);
+        $scope.sections[index] = {
+          id: $scope.sections[index].id,
+          type: 'parameters',
+          content: o.data.content
+        };
+      } else if (o.type === 'moveDown') {
+        var index = getIndex(o.data.id);
+        var before = $scope.sections[index - 1];
+        $scope.sections[index - 1] = $scope.sections[index];
+        $scope.sections[index] = before;
+      } else if (o.type === 'moveUp') {
+        var index = getIndex(o.data.id);
+        var after = $scope.sections[index + 1];
+        $scope.sections[index + 1] = $scope.sections[index];
+        $scope.sections[index] = after;
+      }
+    }
+
+    function getIndex(id) {
+      for (var i = 0; i < $scope.sections.length; ++i) {
+        if ($scope.sections[i].id === id) {
+          return i;
+        }
+      }
+      return -1;
+    }
+
+    $scope.moveUp = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      if (index > 0) {
+        $scope.undoRedo.push({
+          type: 'moveUp',
+          data: {
+            id: id
+          }
+        });
+        var before = $scope.sections[index - 1];
+        $scope.sections[index - 1] = $scope.sections[index];
+        $scope.sections[index] = before;
+      }
+    };
+
+    $scope.moveDown = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      if (index < $scope.sections.length - 1) {
+        $scope.undoRedo.push({
+          type: 'moveDown',
+          data: {
+            id: id
+          }
+        });
+        var after = $scope.sections[index + 1];
+        $scope.sections[index + 1] = $scope.sections[index];
+        $scope.sections[index] = after;
+      }
+    };
+
+    function add(id, obj) {
+      $scope.undoRedo.push({
+        type: 'addSection',
+        data: {
+          id: id,
+          obj: obj
+        }
+      });
+      var index = getIndex(id);
+      $scope.sections = [].concat($scope.sections.slice(0, index + 1), [obj], $scope.sections.slice(index + 1));
+    }
+
+    $scope.addText = function($event, id) {
+      $event.preventDefault();
+      add(id, { id: getNextID(), type: 'text', content: 'FIXME' });
+    };
+
+    $scope.addCallout = function($event, type, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'callout',
+        content: {
+          type: type,
+          body: 'FIXME'
+        }
+      });
+    };
+
+    $scope.addCode = function($event, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'code',
+        content: {
+          codes: [
+            {
+              language: 'fixme',
+              code: '// FIXME'
+            }
+          ]
+        }
+      });
+    };
+
+    $scope.getIntegerIterator = function(v) {
+      var a = [];
+      for (var i = 0; i < v; ++i) {
+        a.push(i);
+      }
+      return a;
+    };
+
+    $scope.deleteSection = function($event, id) {
+      $event.preventDefault();
+      $scope.undoRedo.push({
+        type: 'deleteSection',
+        data: {
+          sections: $scope.sections
+        }
+      });
+      $scope.sections = $.grep($scope.sections, function(e) { return e.id !== id });
+    };
+
+    $scope.deleteLanguage = function($event, id, languageIndex) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      $scope.undoRedo.push({
+        type: 'deleteLanguage',
+        data: {
+          id: id,
+          codes: $scope.sections[index].content.codes
+        }
+      });
+      $scope.sections[index].content.codes = $.grep($scope.sections[index].content.codes, function(e, i) { return i !== languageIndex; });
+    };
+
+    $scope.addLanguage = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      $scope.undoRedo.push({
+        type: 'addLanguage',
+        data: {
+          id: id,
+          codes: $scope.sections[index].content.codes
+        }
+      });
+      $scope.sections[index].content.codes = [].concat($scope.sections[index].content.codes, [{ language: 'FIXME:language|label', code: '// FIXME' }]);
+    };
+
+    $scope.imageToAddAfter = 0;
+    $scope.saveImagePosition = function(id) {
+      $scope.imageToAddAfter = id;
+    };
+    $scope.addImage = function(url) {
+      $('#editor-images').modal('hide');
+      add($scope.imageToAddAfter, {
+        type: 'image',
+        content: {
+          images: [
+            {
+              image: [url]
+            }
+          ]
+        }
+      });
+    };
+
+    $scope.addColumn = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      var section = $scope.sections[index];
+
+      $scope.undoRedo.push({
+        type: 'addColumn',
+        data: {
+          id: id,
+          content: {
+            data: section.content.data,
+            cols: section.content.cols,
+            rows: section.content.rows
+          }
+        }
+      });
+
+      var col = section.content.cols;
+      section.content.data['h-' + col] = section.content.data['h-' + col] || 'FIXME';
+      section.content.cols = section.content.cols + 1;
+      for (var i = 0; i < section.content.rows; ++i) {
+        section.content.data[i + '-' + col] = section.content.data[i + '-' + col] || '';
+      }
+    };
+
+    $scope.deleteColumn = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      var section = $scope.sections[index];
+
+      $scope.undoRedo.push({
+        type: 'deleteColumn',
+        data: {
+          id: id,
+          content: {
+            data: section.content.data,
+            cols: section.content.cols,
+            rows: section.content.rows
+          }
+        }
+      });
+
+      section.content.cols = section.content.cols - 1;
+    };
+
+    $scope.addRow = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      var section = $scope.sections[index];
+
+      $scope.undoRedo.push({
+        type: 'addRow',
+        data: {
+          id: id,
+          content: {
+            data: section.content.data,
+            cols: section.content.cols,
+            rows: section.content.rows
+          }
+        }
+      });
+
+      var rows = section.content.rows;
+      section.content.rows = section.content.rows + 1;
+      for (var i = 0; i < section.content.cols; ++i) {
+        section.content.data[rows + '-' + i] = section.content.data[rows + '-' + i] || '';
+      }
+    };
+
+    $scope.deleteRow = function($event, id) {
+      $event.preventDefault();
+      var index = getIndex(id);
+      var section = $scope.sections[index];
+
+      $scope.undoRedo.push({
+        type: 'deleteRow',
+        data: {
+          id: id,
+          content: {
+            data: section.content.data,
+            cols: section.content.cols,
+            rows: section.content.rows
+          }
+        }
+      });
+
+      section.content.rows = section.content.rows - 1;
+    };
+
+    $scope.addIf = function($event, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'if',
+        content: {
+          condition: 'FIXME:language'
+        }
+      });
+    };
+
+    $scope.addIfNot = function($event, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'ifnot',
+        content: {
+          condition: 'FIXME:language'
+        }
+      });
+    };
+
+    $scope.addEndIf = function($event, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'endif',
+        content: {}
+      });
+    };
+
+    $scope.addTable = function($event, id) {
+      $event.preventDefault();
+      add(id, {
+        id: getNextID(),
+        type: 'parameters',
+        content: {
+          cols: 2,
+          rows: 2,
+          data: {
+            'h-0': 'FIXME 1',
+            'h-1': 'FIXME 2',
+            '0-0': '',
+            '0-1': '',
+            '1-0': '',
+            '1-1': ''
+          }
+        }
+      });
+    };
+
+    function save(preview) {
+      return $http.post($scope.path + '/admin/' + $scope.id, { data: serialize($scope.sections), preview: preview });
+    }
+
+    $scope.save = function($event) {
+      $event.preventDefault();
+      save(true);
+    };
+
+    $scope.preview = function($event) {
+      $event.preventDefault();
+      save(true).then(function(content) {
+        $window.open($scope.path + '/admin/' + $scope.id + '/preview');
+      });
+    };
+
+    $scope.publish = function($event) {
+      $event.preventDefault();
+      if (confirm('Are you sure you want to publish this page?')) {
+        save(false).then(function(content) {
+          $window.location.href = $scope.path + '/' + $scope.slug;
+        });
+      }
+    }
+
+  }]).controller('ImageUploaderController', ['$scope', 'Upload', function($scope, Upload) {
+    $scope.caption = ''
+    $scope.files = [];
+
+    $scope.$watch('files', function () {
+      $scope.upload($scope.files);
+    });
+
+    $scope.upload = function(files) {
+      if (files && files.length) {
+        for (var i = 0; i < files.length; i++) {
+          var file = files[i];
+          Upload.upload({
+            url: $scope.$parent.path + '/admin/images',
+            fields: { caption: $scope.caption },
+            file: file
+          }).success(function (data, status, headers, config) {
+            console.log('uploaded', data);
+            $scope.$parent.addImage(data.url);
+          }).error(function (data, status, headers, config) {
+            console.log('error', data);
+            alert('Error status: ' + status);
+          })
+        }
+      }
+    };
+
+  }]).controller('HistoryController', ['$scope', '$http', '$sce', function($scope, $http, $sce) {
+    $scope.pages = [];
+
+    $scope.init = function(id, path) {
+      $http.get(path + '/admin/' + id + '/versions').then(function(content) {
+        $scope.revisions = content.data.revisions;
+        $scope.diff = {
+          cur: 0,
+          prev: 1
+        };
+      });
+      $scope.path = path;
+    };
+
+    $scope.$watchCollection('diff', function(diff) {
+      if (!diff) {
+        return;
+      }
+      $http.get($scope.path + '/admin/' + $scope.revisions[diff.prev].id + '/' + $scope.revisions[diff.cur].id + '/diff').then(function(content) {
+        $scope.content = $sce.trustAsHtml(content.data);
+      });
+    });
+  }]).directive('contenteditable', ['$document', function($document) {
+    return {
+      require: 'ngModel',
+      link: function(scope, element, attrs, ngModel) {
+        function read() {
+          // use the HTML form to keep the new lines
+          var text = element.html();
+          // replace the HTML newlines by \n
+          text = text.replace(/<div>/g, '<br>').replace(/<\/div>/g, '').replace(/<br>/g, "\n");
+          // replace also all HTML entities
+          text = $('<div />').html(text).text();
+          ngModel.$setViewValue(text);
+        }
+
+        ngModel.$render = function() {
+          element.text(ngModel.$viewValue || "");
+        };
+
+        element.bind("blur keyup change", function() {
+          scope.$apply(read);
+        });
+
+        // force every copy/paste to be plain/text
+        element.bind('paste', function(e) {
+          e.preventDefault();
+          var text = (e.originalEvent || e).clipboardData.getData('text/plain') || '';
+          $document[0].execCommand("insertHTML", false, text);
+        });
+      }
+    };
+  }])
+;