vigetlabs / acts_as_markup

Represent ActiveRecord Markdown, Textile, Wiki text, or RDoc columns as Markdown, Textile, Wikitext or RDoc objects using various external libraries to convert to HTML.

This URL has Read+Write access

Fix typo
brianjlandau (author)
Tue Apr 28 10:07:35 -0700 2009
commit  dc5bf89574ac4e1a1da4498e3ad8a1dfa42e7d6b
tree    5db53af83ee3906fbf1d4965f4782b3403155f45
parent  aeb5f1860b7a70ac32aad5c7cba6d1ddde12839e
acts_as_markup / README.rdoc
raw normal view history
3f189ae0 » brianjlandau 2008-08-11 Add support for Maruku. 1 = Acts as Markup
cf476a2c » brianjlandau 2008-08-06 Initial Commit 2
3 by Brian Landau of Viget Labs <brian.landau@viget.com>
4
5 GitHub Project: http://github.com/vigetlabs/acts_as_markup
6
aeb5f186 » brianjlandau 2009-04-27 Change RDoc URL's 7 RDoc:
8 * http://viget.rubyforge.org/acts_as_markup
9 * http://gitrdoc.com/vigetlabs/acts_as_markup/tree/master
10 * http://vigetlabs.github.com/acts_as_markup
cf476a2c » brianjlandau 2008-08-06 Initial Commit 11
12
13 == DESCRIPTION:
14
c20eefad » brianjlandau 2008-08-08 Revamp some areas of the co... 15 Allows you to specify columns of an ActiveRecord model that contain Markdown,
a05706fa » brianjlandau 2008-08-11 Add RDoc support. 16 Textile, Wiki text and RDoc. You may then use +to_s+ to get the original markup
cf476a2c » brianjlandau 2008-08-06 Initial Commit 17 text or +to_html+ to get the formated HTML.
18
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 19 Additionally you can have a model that contains a column that has a column with
20 markup text, and another that defines what language to process it as. If the field
a05706fa » brianjlandau 2008-08-11 Add RDoc support. 21 is listed as "markdown" "textile", "wikitext" or "rdoc" (case insensitive) it will
22 treat it as such, any other value for markup language will have the value pass
23 through as a normal string.
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 24
cf476a2c » brianjlandau 2008-08-06 Initial Commit 25 This AR extension can use 3 different types of Markdown processing backends:
3f189ae0 » brianjlandau 2008-08-11 Add support for Maruku. 26 BlueCloth, RDiscount, Ruby PEG or Maruku. You specify which one you want to use by setting
cf476a2c » brianjlandau 2008-08-06 Initial Commit 27 a config value in your environment.rb file:
28
29 ActsAsMarkup.markdown_library = :bluecloth
30
31 By default RDiscount will be used.
32
e7b951d4 » chewi 2008-11-18 Documentation for options. 33 You can specify additional options to pass to the markup library by using
49551ebd » chewi 2008-11-18 Fix bad markup. I don't use... 34 <tt>:markdown_options</tt>, <tt>:textile_options</tt> or <tt>:wikitext_options</tt>.
35 RDoc does not support any useful options. The options should be given as an
36 array of arguments. You can specify options for multiple languages when
37 allowing more than one. See each library's documentation for more details on
38 what options are available.
e7b951d4 » chewi 2008-11-18 Documentation for options. 39
cf476a2c » brianjlandau 2008-08-06 Initial Commit 40 == EXAMPLES:
41
42 ==== Using +acts_as_markdown+:
43
44 class Post < ActiveRecrod
45 acts_as_markdown :body
46 end
47
48 @post = Post.find(:first)
49 @post.body.to_s #=> "## Markdown Headline"
50 @post.body.to_html #=> "<h2> Markdown Headline</h2>"
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 51
cf476a2c » brianjlandau 2008-08-06 Initial Commit 52
53 ==== Using +acts_as_textile+:
54
55 class Post < ActiveRecrod
56 acts_as_textile :body
57 end
58
59 @post = Post.find(:first)
c20eefad » brianjlandau 2008-08-08 Revamp some areas of the co... 60 @post.body.to_s #=> "h2. Textile Headline"
61 @post.body.to_html #=> "<h2>Textile Headline</h2>"
62
63
64 ==== Using +acts_as_wikitext+:
65
66 class Post < ActiveRecrod
67 acts_as_wikitext :body
68 end
69
70 @post = Post.find(:first)
71 @post.body.to_s #=> "== Wikitext Headline =="
72 @post.body.to_html #=> "<h2>Wikitext Headline</h2>"
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 73
cf476a2c » brianjlandau 2008-08-06 Initial Commit 74
a05706fa » brianjlandau 2008-08-11 Add RDoc support. 75 ==== Using +acts_as_rdoc+:
76
77 class Post < ActiveRecrod
78 acts_as_rdoc :body
79 end
80
81 @post = Post.find(:first)
82 @post.body.to_s #=> "== RDoc Headline"
83 @post.body.to_html #=> "<h2>RDoc Headline</h2>"
84
85
cf476a2c » brianjlandau 2008-08-06 Initial Commit 86 ==== Using +acts_as_markup+:
87
88 class Post < ActiveRecrod
89 acts_as_markup :language => :markdown, :columns => [:body]
90 end
91
92 @post = Post.find(:first)
93 @post.body.to_s #=> "## Markdown Headline"
94 @post.body.to_html #=> "<h2> Markdown Headline</h2>"
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 95
96
d42a28ff » brianjlandau 2008-08-08 Fix RDoc display issue 97 ==== Using +acts_as_markup+ with <tt>:variable</tt> language:
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 98
99 class Post < ActiveRecrod
78f6d9d2 » brianjlandau 2008-08-12 Make a default column for m... 100 acts_as_markup :language => :variable, :columns => [:body]
1fe308cc » brianjlandau 2008-08-07 Add variable language option. 101 end
102
103 @post = Post.find(:first)
104 @post.markup_language # => "markdown"
105 @post.body.to_s # => "## Markdown Headline"
106 @post.body.to_html # => "<h2> Markdown Headline</h2>"
107
cf476a2c » brianjlandau 2008-08-06 Initial Commit 108
e7b951d4 » chewi 2008-11-18 Documentation for options. 109 ==== Using options
110
111 class Post < ActiveRecord
112 acts_as_markdown :body, :markdown_options => [ :filter_html ]
113 end
114
115 class Post < ActiveRecord
116 acts_as_textile :body, :textile_options => [ [ :filter_html ] ]
117 end
118
119 class Post < ActiveRecord
120 acts_as_wikitext :body, :wikitext_options => [ { :space_to_underscore => true } ]
121 end
122
123
cf476a2c » brianjlandau 2008-08-06 Initial Commit 124 == REQUIREMENTS:
125
c20eefad » brianjlandau 2008-08-08 Revamp some areas of the co... 126 You will need the RedCloth[http://whytheluckystiff.net/ruby/redcloth/] library
127 for processing the Textile text, and the Wikitext[http://wikitext.rubyforge.org/]
128 library for processing wikitext.
cf476a2c » brianjlandau 2008-08-06 Initial Commit 129
130 You will also need to install some type of Markdown processor.
131 The three options currently supported are:
132
133 * BlueCloth
134 * RDiscount[http://github.com/rtomayko/rdiscount]
135 * {Ruby PEG}[http://github.com/rtomayko/rpeg-markdown/tree/master]
3f189ae0 » brianjlandau 2008-08-11 Add support for Maruku. 136 * Maruku[http://maruku.rubyforge.org/]
cf476a2c » brianjlandau 2008-08-06 Initial Commit 137
138 == INSTALL:
139
140 <tt>sudo gem install acts_as_markup</tt>
141
142 Add "+acts_as_markup+" to your environment.rb:
143
144 config.gem "acts_as_markup"
145
3d9bd146 » brianjlandau 2008-08-14 Improve extension file hand... 146 == CONTRIBUTING:
147
148 Make a fork on GitHub, make your changes and do a pull request. Good places to start are adding new Markdown libraries or new markup languages, here's instructions for both:
149
150 === Instructions for how to add a new Markdown Library:
151
152 1. Add another item to the <tt>ActsAsMarkup::MARKDOWN_LIBS</tt> hash in the form of:
153 :bluecloth => {:class_name => "BlueCloth",
154 :lib_name => "bluecloth"}
155 <tt>:lib_name</tt> should be the name needed to require the library, while <tt>:class_name</tt> should be the class that we are making an instance of.
156 2. If you need to modify the object in anyway (e.g. to add a <tt>to_s</tt> or <tt>to_html</tt> method), add a file to the "lib/acts_as_markup/exts/" directory.
157 3. Add appropriate tests (see current tests).
158
159 === Instructions for how to add a new Markup Language:
160
161 1. Add a "<tt>when</tt>" statement to the "<tt>case</tt>" statement in <tt>acts_as_markup</tt>. The "<tt>when</tt>" statement should match with a symbol that represents the language name in some way (e.g. "<tt>:markdown</tt>").
162 2. In the "<tt>when</tt>" block you need to set the "<tt>klass</tt>" local variable and require the library and the extension file if you need one (use the special <tt>require_extensions</tt> method to require extensions).
163 3. Add the same lines you added to the previous "<tt>when</tt>" statement to the "<tt>:variable</tt>" "<tt>when</tt>" statement. But replace "<tt>klass</tt>" with "<tt>language_klass</tt>" (e.g. "<tt>markdown_klass</tt>").
164 4. Add a relevant "<tt>when</tt>" statement to the <tt>class_eval</tt> block for the "<tt>:variable</tt>" language option. This should look something like:
165 when /markdown/i
e7b951d4 » chewi 2008-11-18 Documentation for options. 166 markup_klasses[:markdown].new self[col].to_s
3d9bd146 » brianjlandau 2008-08-14 Improve extension file hand... 167 5. Add a convenience method (e.g. "<tt>acts_as_markdown</tt>")
168 6. Add an extension file to the "lib/acts_as_markup/exts/" directory if you need to modify the object in anyway.
169 7. Add appropriate tests (see current tests).
170