Permalink
Browse files

rewrite README, add LICENSE.txt

  • Loading branch information...
1 parent 55ce068 commit 4624544cc473251e881ceed1784ea1487d1a0565 @phlipper committed Jan 7, 2013
Showing with 189 additions and 51 deletions.
  1. +20 −0 LICENSE.txt
  2. +169 −51 README.md
View
@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright © 2013 Phil Cohen <github@phlippers.net>
+
+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.
View
@@ -1,81 +1,199 @@
-markitup-rails
-========================
+# markitup-rails
-This is a gem that contains the vendor assets for [markitup](http://markitup.jaysalvat.com/home/).
+## Description
-## Support
+The [markItUp!](http://markitup.jaysalvat.com/home/) universal markup editor, bundled for Rails 3.1+ Asset Pipeline.
-Should support rails 3.0 and higher.
+markItUp! is a JavaScript plug-in built on the jQuery library. It allows you to turn any textarea into a markup editor. HTML, Textile, Wiki Syntax, Markdown, BBcode or even your own Markup system can be easily implemented.
-### Supported markup languages:
+`markitup-rails` ships with several markup "sets" and editor "skins" including:
+### Markup Sets
+
+* `bbcode`
+* `css`
+* `default`
+* `dotclear`
* `html`
-* `textile`
* `markdown`
+* `markmin`
+* `rest`
+* `textile`
+* `texy`
+* `txt2tags`
* `wiki`
-* `texty`
-* `css`
+* `xbbcode`
+
+### Editor Skins
+
+* `markitup`
+* `simple`
+
+
+## Requirements
+
+This gem requires Rails 3.1+ and has been tested on the following versions:
+
+* 3.1
+* 3.2
+
+This gem requires Ruby 1.9+ and has been tested against the following Ruby versions:
+
+* 1.9.2
+* 1.9.3
+* JRuby
+* Rubinius
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "markitup-rails"
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install markitup-rails
+```
+
+
+## Configuration
+
+The `Markitup::Rails` module accepts a `configure` block with options to customize the engine behavior.
+
+Place any custom configuration in a file such as `config/initializers/markitup_rails.rb`.
+
+
+### Layout
+
+Set the `layout` option to customize the layout used by the AJAX live preview:
+
+```ruby
+Markitup::Rails.configure do |config|
+ config.layout = "other" # default is `markitup`
+end
+```
+
+You may also override the default locally by creating a new layout file at `app/views/layouts/markitup.html.erb`.
+
+### Formatter
+
+Set the `formatter` option to customize the renderer for the preview. This can be any object that responds to `call` and which takes a single argument with the markup to render:
+
+```ruby
+Markitup::Rails.configure do |config|
+ config.formatter = -> markup { BBCodeParser.parse(markup) }
+end
+```
+
+### Route
+
+`markitup-rails` provides a URL endpoint that be mounted to support a live server-side preview of markItUp! content.
+
+To enable, mount the engine in your `config/routes.rb` file:
+
+```ruby
+mount Markitup::Rails::Engine, at: "markitup", as: "markitup"
+```
+
+This will create a URL helper for `markitup.preview_url` which will route to `/markitup/preview`.
+
+The preview URL will render the editor content using the `config.formatter` and display the content within the `config.layout`.
+
## Usage
-### Installing the Gem
+For Rails 3.1 and greater, the files will be added to the asset pipeline and available for you to use.
+
+To enable the markItUp! editor in your application, you will need to include the appropriate JavaScript and Stylesheet files for the Set and Skin you wish to use.
+
+Example:
+
+* Add the following line to the file `app/assets/javascripts/application.js` (or other [sprockets](https://github.com/sstephenson/sprockets) manifest):
+
+```javascript
+//= require markitup
+//= require markitup/sets/xbbcode/set
+```
+
+* Add the following line to the file `app/assets/stylesheets/application.css`:
+
+```css
+*= require markitup/skins/markitup/style
+*= require markitup/sets/xbbcode/style
+```
+
+You may also include the styles in your SCSS file directly:
+
+```scss
+@import "markitup/skins/markitup/style";
+@import "markitup/sets/xbbcode/style";
+```
+
+
+### Using markItUp!
+
+Example:
-Require `markitup-rails` in your `Gemfile`.
+```coffee
+jQuery ->
- gem 'markitup-rails'
-
-Install the gem via `bundle` command.
+ # Target all text areas
+ $("textarea").markItUp mySettings
+ # Target a specific ID
+ $("#my_id").markItUp mySettings
-### Using it in your application
+ # Target a specific class
+ $("textarea.markitup").markItUp mySettings
+```
-Add to `application.css`
+See the [markItUp! documentation](http://markitup.jaysalvat.com/documentation/) for more information.
- *= require markitup
- *= require markitup-[markup lang]
-Example
+## Contributing
- *= require markitup
- *= require markitup-textile
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a Pull Request
-And in `application.js`
- //= require markitup
- //= require markitup-[markup lang]
+## Contributors
-Example
+Many thanks go to the following who have contributed to making this gem even better:
- //= require markitup
- //= require markitup-textile
+* **[@ugorelik](https://github.com/ugorelik)**
+ * initial version
+* **[@phlipper](https://github.com/phlipper)**
+ * complete rewrite as an engine for Rails 3.1+
+ * add AJAX live preview support
+ * add support for Sets and Skins, add many defaults to choose from
-### Using markitup
+## License
-Include in either `application.js` or another file that will be included in the pipelin:
+**markitup-rails**
- // To target all text areas
- $(document).ready(function() {
- $("textarea").markItUp(mySettings);
- });
-
- //----- OR
-
- // To target a specific ID
- $(document).ready(function() {
- $("textarea#my_id").markItUp(mySettings);
- });
-
- //----- OR
-
- // To target a specific class
- $(document).ready(function() {
- $("textarea.markitup").markItUp(mySettings);
- });
+* Freely distributable and licensed under the [MIT license](http://phlipper.mit-license.org/2013/license.html).
+* Copyright (c) 2013 Phil Cohen (github@phlippers.net) [![endorse](http://api.coderwall.com/phlipper/endorsecount.png)](http://coderwall.com/phlipper)
+* http://phlippers.net/
-
-See the [markitup documentation](http://markitup.jaysalvat.com/documentation/) for more info.
+**markItUp!**
-----
+* Author: [Jay Salvat](http://www.jaysalvat.com/)
+* Licence: MIT/GPL
+* http://markitup.jaysalvat.com/
-*Based on the [blueprint-rails gem](https://github.com/bai/blueprint-rails)*
+markItUp! is released under both the MIT and GPL Open Source licenses.
+In short, this means that markItUp! is totally Free, and you can do whatever you want with it. You are only obligated to keep the credits in place.

0 comments on commit 4624544

Please sign in to comment.