Skip to content
Newer
Older
100644 171 lines (112 sloc) 5.62 KB
fd9a367 @nex3 Excise Sass from within files.
nex3 authored
1 # Haml
35f7e17 Initial upload.
hcatlin authored
2
ce1b04d @joliss Add Travis badge
joliss authored
3 [![Build Status](https://secure.travis-ci.org/haml/haml.png?branch=master)](http://travis-ci.org/haml/haml)
4
dd1359d @norman Updated README
norman authored
5 Haml is a templating engine for HTML. It's designed to make it both easier and
6 more pleasant to write HTML documents, by eliminating redundancy, reflecting the
7 underlying structure that the document represents, and providing an elegant syntax
8 that's both powerful and easy to understand.
d2e81e2 Made a few changes to the readme (using single quotes) and added an o…
hcatlin authored
9
dd1359d @norman Updated README
norman authored
10 ## Basic Usage
55e9de4 @nex3 Added basic Sass tutorial to README.
nex3 authored
11
dd1359d @norman Updated README
norman authored
12 Haml can be used from the command line or as part of a Ruby web framework. The
13 first step is to install the gem:
c1b21a2 @nex3 Merb handler for Sass. This includes a pretty major restructuring of …
nex3 authored
14
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
15 gem install haml
c1b21a2 @nex3 Merb handler for Sass. This includes a pretty major restructuring of …
nex3 authored
16
dd1359d @norman Updated README
norman authored
17 After you write some Haml, you can run
3d490d2 @nex3 Clean up the Using section of the README.
nex3 authored
18
19 haml document.haml
20
dd1359d @norman Updated README
norman authored
21 to compile it to HTML. For more information on these commands, check out
3d490d2 @nex3 Clean up the Using section of the README.
nex3 authored
22
23 haml --help
24
dd1359d @norman Updated README
norman authored
25 To use Haml programatically, check out the [YARD
f3477eb @norman Merge branch 'stable'
norman authored
26 documentation](http://haml.info/docs/yardoc/).
55e9de4 @nex3 Added basic Sass tutorial to README.
nex3 authored
27
dd1359d @norman Updated README
norman authored
28 ## Using Haml with Rails
29
30 To use Haml with Rails, simply add Haml to your Gemfile and run `bundle`.
31
32 If you'd like to replace Rails's Erb-based generators with Haml, add
33 [haml-rails](https://github.com/indirect/haml-rails) to your Gemfile as well.
c1b21a2 @nex3 Merb handler for Sass. This includes a pretty major restructuring of …
nex3 authored
34
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
35 ## Formatting
7db85d7 Updated the README and updated inline rdoc
packagethief authored
36
dd1359d @norman Updated README
norman authored
37 The most basic element of Haml is a shorthand for creating HTML:
00ef3f9 @nex3 Better facilities for whitespace-sensitive elements. See REFERENCE en…
nex3 authored
38
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
39 %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents
00ef3f9 @nex3 Better facilities for whitespace-sensitive elements. See REFERENCE en…
nex3 authored
40
dd1359d @norman Updated README
norman authored
41 No end-tag is needed; Haml handles that automatically. If you prefer HTML-style
42 attributes, you can also use:
3b36078 @nex3 [Haml] Mention the new attribute syntax in the README.
nex3 authored
43
44 %tagname(attr1='value1' attr2='value2') Contents
45
dd1359d @norman Updated README
norman authored
46 Adding `class` and `id` attributes is even easier. Haml uses the same syntax as
47 the CSS that styles the document:
47616c9 @nex3 Adding support for alternate doctypes (see REFERENCE). Also added a N…
nex3 authored
48
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
49 %tagname#id.class
00ef3f9 @nex3 Better facilities for whitespace-sensitive elements. See REFERENCE en…
nex3 authored
50
dd1359d @norman Updated README
norman authored
51 In fact, when you're using the `<div>` tag, it becomes _even easier_. Because
52 `<div>` is such a common element, a tag without a name defaults to a div. So
47616c9 @nex3 Adding support for alternate doctypes (see REFERENCE). Also added a N…
nex3 authored
53
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
54 #foo Hello!
00ef3f9 @nex3 Better facilities for whitespace-sensitive elements. See REFERENCE en…
nex3 authored
55
64ee1f0 @nex3 Moving Haml reference stuff to the Haml module and out of README.
nex3 authored
56 becomes
7ea068e @nex3 Added an XML processing directive tag.
nex3 authored
57
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
58 <div id='foo'>Hello!</div>
84fdde1 @nex3 Get rid of trailing whitespace.
nex3 authored
59
dd1359d @norman Updated README
norman authored
60 Haml uses indentation to bring the individual elements to represent the HTML
61 structure. A tag's children are indented beneath than the parent tag. Again, a
62 closing tag is automatically added. For example:
b0300b8 Introducing the new buffered branch into Trunk.
hcatlin authored
63
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
64 %ul
65 %li Salt
66 %li Pepper
b0300b8 Introducing the new buffered branch into Trunk.
hcatlin authored
67
64ee1f0 @nex3 Moving Haml reference stuff to the Haml module and out of README.
nex3 authored
68 becomes:
a99fd55 @nex3 Added more functionality to comments (see REFERENCE). Also added a few
nex3 authored
69
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
70 <ul>
71 <li>Salt</li>
72 <li>Pepper</li>
73 </ul>
40b3d61 @nex3 Added a new backslash escape character.
nex3 authored
74
64ee1f0 @nex3 Moving Haml reference stuff to the Haml module and out of README.
nex3 authored
75 You can also put plain text as a child of an element:
b0300b8 Introducing the new buffered branch into Trunk.
hcatlin authored
76
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
77 %p
78 Hello,
79 World!
25f14b2 @nex3 The ~ character with a block works the same on its own as when attach…
nex3 authored
80
dd1359d @norman Updated README
norman authored
81 It's also possible to embed Ruby code into Haml documents. An equals sign, `=`,
82 will output the result of the code. A hyphen, `-`, will run the code but not
83 output the result. You can even use control statements like `if` and `while`:
b0300b8 Introducing the new buffered branch into Trunk.
hcatlin authored
84
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
85 %p
86 Date/Time:
87 - now = DateTime.now
88 %strong= now
89 - if now > DateTime.parse("December 31, 2006")
90 = "Happy new " + "year!"
7db85d7 Updated the README and updated inline rdoc
packagethief authored
91
dd1359d @norman Updated README
norman authored
92 Haml provides far more tools than those presented here. Check out the [reference
f3477eb @norman Merge branch 'stable'
norman authored
93 documentation](http://haml.info/docs/yardoc/file.REFERENCE.html)
33f23a1 @nex3 [Haml] Fix a bit in the README.
nex3 authored
94 for full details.
82ff534 Created a README and set up rdoc
packagethief authored
95
fd9a367 @nex3 Excise Sass from within files.
nex3 authored
96 ### Indentation
55e9de4 @nex3 Added basic Sass tutorial to README.
nex3 authored
97
dd1359d @norman Updated README
norman authored
98 Haml's indentation can be made up of one or more tabs or spaces. However,
99 indentation must be consistent within a given document. Hard tabs and spaces
100 can't be mixed, and the same number of tabs or spaces must be used throughout.
55e9de4 @nex3 Added basic Sass tutorial to README.
nex3 authored
101
76eed63 @jonallured Add Contribution info to README
jonallured authored
102 ## Contributing
103
104 Contributions are welcomed, but before you get started please read the
f3477eb @norman Merge branch 'stable'
norman authored
105 [guidelines](http://haml.info/development.html#contributing).
76eed63 @jonallured Add Contribution info to README
jonallured authored
106
3374300 @jonallured Add notes on setup for contributing
jonallured authored
107 After forking and then cloning the repo locally, install Bundler and then use it
108 to install the development gem dependecies:
109
110 gem install bundler
111 bundle install
112
113 Once this is complete, you should be able to run the test suite:
114
115 rake
116
117 You'll get a warning that you need to install haml-spec, so run this:
118
119 git submodule update --init
120
121 At this point `rake` should run without error or warning and you are ready to
122 start working on your patch!
123
f522cf3 @norman Make test requires consistent across platforms
norman authored
124 Note that you can also run just one test out of the test suite if you're working
125 on a specific area:
126
127 ruby -Itest test/helper_test.rb -n test_buffer_access
128
beb46af @norman Added note about testing on 1.8 and 1.9.
norman authored
129 Haml supports Ruby 1.8.7 and higher, so please make sure your changes run on
130 both 1.9 and 1.8.
f522cf3 @norman Make test requires consistent across platforms
norman authored
131
dbd3c62 @nex3 Convert the README to markdown.
nex3 authored
132 ## Authors
82ff534 Created a README and set up rdoc
packagethief authored
133
dd1359d @norman Updated README
norman authored
134 Haml was created by [Hampton Catlin](http://hamptoncatlin.com), the author of
135 the original implementation. However, Hampton doesn't even know his way around
136 the code anymore and now just occasionally consults on the language issues.
3eda43c @nex3 Update the Authors section of the README.
nex3 authored
137
dd1359d @norman Updated README
norman authored
138 [Nathan Weizenbaum](http://nex-3.com) was for many years the primary developer
30b45be @norman Add myself as maintainer
norman authored
139 and architect of the "modern" Ruby implementation of Haml. His hard work
140 endlessly answering forum posts, fixing bugs, refactoring, finding speed
141 improvements, writing documentation, and implementing new features is what has
142 kept the project alive.
143
144 [Norman Clarke](http://github.com/norman), the author of Haml Spec and the Haml
145 implementation in Lua, took over as maintainer in April 2012.
8143e16 an update to the authorship in the README that was a loooong time coming
hcatlin authored
146
dd1359d @norman Updated README
norman authored
147 ## License
148
149 Some of Nathan's work on Haml was supported by Unspace Interactive.
6c8ff1c @nex3 Local variables can now be set via Haml::Engine, rather than solely v…
nex3 authored
150
64ee1f0 @nex3 Moving Haml reference stuff to the Haml module and out of README.
nex3 authored
151 Beyond that, the implementation is licensed under the MIT License.
dd1359d @norman Updated README
norman authored
152
153 Copyright (c) 2006-2009 Hampton Catlin and Nathan Weizenbaum
154
155 Permission is hereby granted, free of charge, to any person obtaining a copy of
156 this software and associated documentation files (the "Software"), to deal in
157 the Software without restriction, including without limitation the rights to
158 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
159 the Software, and to permit persons to whom the Software is furnished to do so,
160 subject to the following conditions:
161
162 The above copyright notice and this permission notice shall be included in all
163 copies or substantial portions of the Software.
164
165 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
166 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
167 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
168 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
169 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
170 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.