Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update documentation formatting

  • Loading branch information...
commit e4c485e6679b8efa71fe90f93c8353c598cf87d4 1 parent 326153a
@paularmstrong authored
View
34 README.md
@@ -1,8 +1,10 @@
-# Swig
+Swig
+====
[Swig](http://paularmstrong.github.com/swig/) is a fast, Django-like template engine for node.js.
-## Features
+Features
+--------
* Incredibly [fast][1]!
* Available for node.js **and** major web browsers!
@@ -13,15 +15,18 @@
* Lots of iteration and conditionals supported.
* Extendable and customizable.
-## Installation
+Installation
+------------
npm install swig
-## Documentation
+Documentation
+-------------
-All documentation can be viewed online. [Documentation Table of Contents](https://github.com/paularmstrong/swig/tree/master/docs)
+All documentation can be viewed online. [Documentation Table of Contents](https://github.com/paularmstrong/swig/tree/master/docs#readme)
-## Basic Example
+Basic Example
+-------------
### Template code
@@ -36,7 +41,7 @@ All documentation can be viewed online. [Documentation Table of Contents](https:
### node.js code
- var template = require('Swig');
+ var template = require('swig');
var tmpl = template.fromFile('/path/to/template.html');
tmpl.render({
pagename: 'awesome people',
@@ -52,20 +57,13 @@ All documentation can be viewed online. [Documentation Table of Contents](https:
<li>Jane</li>
</ul>
-## How it works
+How it works
+------------
Swig reads template files and translates them into cached javascript functions. When we later render a template we call the evaluated function, passing a context object as an argument. This makes the rendering [_very fast_][1].
-## Template syntax
-
-* `{%` opens the start of a logic tag
-* `%}` closes a logic tag
-* `{{` opens variable
-* `}}` closes the variable
-* `{#` opens a comment block
-* `#}` closes a comment block
-
-## License
+License
+-------
Copyright (c) 2010-2011 Paul Armstrong, Dusko Jordanovski
View
22 docs/README.md
@@ -1,15 +1,19 @@
-# Swig Documentation
+Swig Documentation
+==================
-## Table of Contents
+Table of Contents
+-----------------
-1. [Getting Started](getting-started.md)
-1. [Filters](filters.md)
-1. [Tags](tags.md)
-1. [Template Inheritance](inheritance.md)
-1. [Integrating with Express](express.md)
-1. [In the Browser](browser.md)
+1. [Getting Started](docs/getting-started.md#getting-started)
+1. [Syntax](docs/syntax.md#syntax)
+1. [Filters](docs/filters.md#filters)
+1. [Tags](docs/tags.md#tags)
+1. [Template Inheritance](docs/inheritance.md#inheritance)
+1. [Integrating with Express](docs/express.md#express)
+1. [In the Browser](docs/browser.md#browser)
-## Examples
+Examples
+--------
1. [Basic Usage](../examples/basic)
1. [Custom Tags](../examples/custom_tags)
View
7 docs/browser.md
@@ -1,4 +1,5 @@
-# Swig in Your Browser
+Swig in Your Browser <a name="browser" href="#browser">#</a>
+====================
To compile Swig for rendering in the browser, clone the Swig repository and run the following in your command-line:
@@ -13,7 +14,7 @@ Swig relies heavily on [underscore.js](http://documentcloud.github.com/underscor
You should only need one of these. If you already include _underscore.js_ in your website, choose _swig.js_ for development and _swig.min.js_ for production. If you have not included _underscore.js_ and you don't intend to, choose _swig.pack.js_ for development and _swig.pack.min.js_ for production.
-## The API
+## The API <a name="api" href="#api">#</a>
Swig's API in the browser is the same as [its API for node.js](getting-started.md), with the only difference being that you cannot use the `swig.fromFile` method, since browsers do not have a filesystem.
@@ -32,7 +33,7 @@ When you render mypage, `mypage.render({});`, you will see
<p>Oh hey there!</p>
-## Known Issues
+## Known Issues <a name="issues" href="#issues">#</a>
* Opera and Internet Explorer fail to comply with the date filter format `r`.
* Internet Explorer 9.0 **in compatibility mode** and IE 6 through 8:
View
12 docs/custom-tags.md
@@ -1,4 +1,5 @@
-# Custom Tags
+Custom Tags <a name="custom-tags" href="#custom-tags">#</a>
+===========
Swig makes it easy to write custom tags specific for your project.
@@ -6,7 +7,8 @@ First, make sure to include your node.js file that declares your tags in the swi
swig.init({ tags: require('mytags') });
-## Requirements
+Requirements <a name="requirements" href="#requirements">#</a>
+------------
First, include the Swig parser and helpers.
@@ -20,7 +22,8 @@ Define your tag and whether or not it requires an "end" tag:
};
exports.mytag.ends = true;
-## A Really Simple Tag
+A Really Simple Tag <a name="example" href="#example">#</a>
+-------------------
To parse a swig variable with or without filters into a variable token, eg. `bar` or `foo|lowercase`
@@ -70,6 +73,7 @@ Output:
<h1>Scrumdiddlyumptious</h1>
<p>Tacos</p>
-## Write Your Own
+Write Your Own <a name="write-your-own" href="#write-your-own">#</a>
+--------------
To best understand how to write your own tag, reference [`swig/lib/tags.js`](../lib/tags.js) to see how the internal tags are written. These will give you a pretty clear indication of how to write your own.
View
3  docs/express.md
@@ -1,4 +1,5 @@
-# Using Swig in Express for View Rendering
+Using Swig in Express for View Rendering <a name="express" href="#express">#</a>
+========================================
Swig is compatible with [Express][1]! It's very easy to set up your Express-based node project to use Swig as its template renderer. Here's how:
View
58 docs/filters.md
@@ -1,16 +1,17 @@
-# Variable Filters
+Variable Filters <a name="filters" href="#filters">#</a>
+================
Used to modify variables. Filters are added directly after variable names, separated by the pipe (|) character. You can chain multiple filters together, applying one after the other in succession.
-## Example
+Example
+-------
{{ name|title }} was born on {{ birthday|date('F jS, Y') }} and has {{ bikes|length|default("zero") }} bikes.
-<a id="built_in" href="#built_in"></a>
+Built-In Filters <a name="built-in" href="#built-in">#</a>
+----------------
-## Built-In Filters
-
-### add(value) <a id="default" href="#default">¶</a>
+### add(value) <a name="default" href="#default">#</a>
Adds the value to the variable. Strings that can be converted to integers will be summed, not concatenated, as in the example below.
@@ -18,7 +19,7 @@ Adds the value to the variable. Strings that can be converted to integers will b
1. <var>**value**</var> (_mixed_) The value to add to the variable before printing it to the page. Accepts any `array`, `object`, `number`, and `string`.
-### addslashes <a id="addslashes" href="#addslashes"></a>
+### addslashes <a name="addslashes" href="#addslashes">#</a>
Returns a string with backslashes in front of characters that need to be quoted for database queries, etc.
@@ -26,11 +27,11 @@ Returns a string with backslashes in front of characters that need to be quoted
* double quote `"`
* backslash `\`
-### capitalize <a id="capitalize" href="#capitalize"></a>
+### capitalize <a name="capitalize" href="#capitalize">#</a>
Capitalize the first character in the string.
-### date(format) <a id="date" href="#date"></a>
+### date(format) <a name="date" href="#date">#</a>
Convert a valid date into a format as specified. Mostly conforms to [php.net's date formatting](http://php.net/date).
@@ -232,7 +233,7 @@ Convert a valid date into a format as specified. Mostly conforms to [php.net's d
</tbody>
</table>
-### default(value) <a id="default" href="#default"></a>
+### default(value) <a name="default" href="#default">#</a>
If the variable is `undefined`, `null`, or `false`, a default return value can be specified.
@@ -240,7 +241,7 @@ If the variable is `undefined`, `null`, or `false`, a default return value can b
1. <var>**value**</var> (_mixed_) Fallback value if the variable is falsy.
-### escape([type]) / e([type]) <a id="escape" href="#escape"></a>
+### escape([type]) / e([type]) <a name="escape" href="#escape">#</a>
Force escape the output of the variable. Optionally use `e` as a shortcut filter name. This filter will be applied by default if [autoescape](getting-started.md) is turned on.
@@ -332,11 +333,11 @@ Pass `js` as the type to your escape filter to toggle escaping as JavaScript.
1. <var>**type**</var> (_string_) _optional_ passing "js" as the type will force JavaScript-safe escaping.
-### first <a id="first" href="#first"></a>
+### first <a name="first" href="#first">#</a>
Returns the first element of an array. Uses [underscore.js first](http://documentcloud.github.com/underscore/#first)
-### join(glue) <a id="join" href="#join"></a>
+### join(glue) <a name="join" href="#join">#</a>
If the value is an Array, you can join each value with a delimiter and return it as a string.
@@ -344,27 +345,27 @@ If the value is an Array, you can join each value with a delimiter and return it
1. <var>**glue**</var> (_string_) Concatenation string to join each item in the array with.
-### json_encode <a id="json_encode" href="#json_encode"></a>
+### json_encode <a name="json_encode" href="#json_encode">#</a>
Return a JSON string of the variable.
-### last <a id="last" href="#last"></a>
+### last <a name="last" href="#last">#</a>
Returns the last element of an array. Uses [underscore.js last](http://documentcloud.github.com/underscore/#last)
-### length <a id="length" href="#length"></a>
+### length <a name="length" href="#length">#</a>
Return the `length` property of the variable. If the variable is an object, this will return the length of the keys on the object.
-### lower <a id="lower" href="#lower"></a>
+### lower <a name="lower" href="#lower">#</a>
Return the variable in all lowercase letters.
-### raw <a id="raw" href="#raw"></a>
+### raw <a name="raw" href="#raw">#</a>
Do not escape the output of the variable.
-### replace(search, replace[, flags]) <a id="replace" href="#replace"></a>
+### replace(search, replace[, flags]) <a name="replace" href="#replace">#</a>
Uses built-in JavaScript replace method. Provide a regular-expression or a string and a replacement string.
@@ -374,37 +375,36 @@ Uses built-in JavaScript replace method. Provide a regular-expression or a strin
2. <var>**replace**</var> (_string_) a string to replace the matched parts from <var>search</var>
3. <var>**flags**</var> (_string_) _optional_ Regular expression flags. [[reference]](https://developer.mozilla.org/en/JavaScript/Guide/Regular_Expressions#Advanced_Searching_With_Flags)
-### reverse <a id="reverse" href="#reverse"></a>
+### reverse <a name="reverse" href="#reverse">#</a>
If the value is an Array, this filter will reverse all items in the array.
-### striptags <a id="striptags" href="#striptags"></a>
+### striptags <a name="striptags" href="#striptags">#</a>
Strip all HTML/XML tags.
-### title <a id="title" href="#title"></a>
+### title <a name="title" href="#title">#</a>
Change the output to title case–the first letter of every word will uppercase, while all the rest will be lowercase.
-### uniq <a id="uniq" href="#uniq"></a>
+### uniq <a name="uniq" href="#uniq">#</a>
Produces a duplicate-free version of the array. Uses [underscore.js uniq](http://documentcloud.github.com/underscore/#uniq)
-### upper <a id="upper" href="#upper"></a>
+### upper <a name="upper" href="#upper">#</a>
Return the variable in all uppercase letters
-### url_encode <a id="url_encode" href="#url_encode"></a>
+### url_encode <a name="url_encode" href="#url_encode">#</a>
Encode a URI component.
-### url_decode <a id="url_decode" href="#url_decode"></a>
+### url_decode <a name="url_decode" href="#url_decode">#</a>
Decode a URI component.
-<a id="custom_filters" href="#custom_filters"></a>
-
-## Writing Custom Filters
+Writing Custom Filters <a name="custom-filters" href="#custom-filters">#</a>
+----------------------
Custom filters are very easy to write for your own project that uses Swig.
View
13 docs/getting-started.md
@@ -1,6 +1,8 @@
-# Getting Started
+Getting Started <a name="getting-started" href="#getting-started">#</a>
+===============
-## The Init
+Init Swig <a name="init" href="#init">#</a>
+---------
In order to start using Swig, you must intialize it. Swig can be configured using the following:
@@ -47,14 +49,17 @@ The directory to search for templates. If a template passed to `swig.fromFile` i
Use this to set any custom tags and/or override any of the built-in tags. For more information on writing your own tags, see the [custom tags guide](custom-tags.md).
-## Parsing a Template
+Parsing a Template <a name="parsing" href="#parsing">#</a>
+------------------
You have 2 methods for creating a template object:
swig.fromFile("path/to/template/file.html");
swig.fromString("Template string here");
-## Rendering a Template
+Rendering a Template <a name="rendering" href="#rendering">#</a>
+--------------------
+
Both of these methods will give you a template object on which you call the render method passing it a map of context values.
var tpl = swig.fromFile("path/to/template/file.html");
View
6 docs/inheritance.md
@@ -1,10 +1,12 @@
-# Template Inheritance
+Template Inheritance <a name="inheritance" href="#inheritance">#</a>
+====================
Swig borrows much of its implementation from Django's templates–template inheritance with `extends` and `block`s are no exception.
Unlike other, more basic template languages, Swig is able to render a single template that extends from multiple templates in a chain in a very powerful way.
-## Basic Example
+Basic Example <a name="example" href="#example">#</a>
+-------------
### layout.html
View
12 docs/syntax.md
@@ -1,4 +1,5 @@
-# Template Syntax
+Template Syntax <a name="syntax" href="#syntax">#</a>
+===============
Swig uses the same template syntax as Django Templates
@@ -11,7 +12,8 @@ Swig uses the same template syntax as Django Templates
* `{%` opens the start of a logic tag
* `%}` closes a logic tag
-## Variables
+Variables <a name="variables" href="#variables">#</a>
+---------
Used to print a variable to the template. If the variable is not in the context we don't get an error, rather an empty string. You can use dot notation to access object proerties or array memebers.
@@ -21,13 +23,15 @@ Variables also are able to be transformed via [filters](filters.md).
By default, all variables will be escaped for safe HTML output. For more information, read about the [escape filter](filters.md#escape).
-## Comments
+Comments <a name="comments" href="#domments">#</a>
+--------
Comment tags are simply ignored. Comments can't span multitple lines.
{# This is a comment #}
-## Logic
+Logic <a name="logic" href="#logic">#</a>
+-----
Logic tags are operational blocks that have internal logic on how the template should proceed. Read more about [tags](tags.md).
View
36 docs/tags.md
@@ -1,33 +1,35 @@
-# Tags
+Tags <a name="tags" href="#tags">#</a>
+====
-## Built-in Tags
+Built-in Tags <a name="builtin" href="#builtin">#</a>
+-------------
-### extends <a id="extends" href="#extends"></a>
+### extends <a name="extends" href="#extends">#</a>
Makes the current template extend a parent template. This tag must be the first item in your template.
See [Template inheritance](inheritance.md) for more information.
-### block <a id="block" href="#block"></a>
+### block <a name="block" href="#block">#</a>
Defines a block in a template that can be overridden by a template extending this one and/or will override the current template's parent template block of the same name.
See [Template inheritance](inheritance.md) for more information.
-### parent <a id="parent" href="#parent"></a>
+### parent <a name="parent" href="#parent">#</a>
Inject the content from the current `block` in the parent template into the child template.
See [Template inheritance](inheritance.md) for more information.
-### include <a id="include" href="#include"></a>
+### include <a name="include" href="#include">#</a>
Includes a template in it's place. The template is rendered within the current context. Does not use and {% endinclude %}.
{% include template_path %}
{% include "path/to/template.js" %}
-### for <a id="for" href="#for"></a>
+### for <a name="for" href="#for">#</a>
For loops have 4 special context variables accessible inside of the loop:
@@ -48,7 +50,7 @@ You can also apply filters to the object that you are iterating over.
The array `y` will first be reversed before looping over it.
{% endfor %}
-#### empty <a id="empty" href="#empty"></a>
+#### empty <a name="empty" href="#empty">#</a>
For loops have a special tag available to them called `{% empty %}`.
@@ -60,7 +62,7 @@ If the loop object is empty or `length === 0`, the content following the `empty`
There are no people yet!
{% endfor %}
-### if <a id="if" href="#if"></a>
+### if <a name="if" href="#if">#</a>
All normal JavaScript-valid if statements are supported, including some extra helpful syntaxes:
@@ -88,7 +90,7 @@ All normal JavaScript-valid if statements are supported, including some extra he
If x is a value that is present in y, this will return true.
{% endif %}
-#### else and else if <a id="else" href="#else"></a>
+#### else and else if <a name="else" href="#else">#</a>
Also supports using the `{% else %}` and `{% else if ... %}` tags within an if-block. Using `{% else [if ...] %}` anywhere outside an immediate parent if-block will throw an exception.
@@ -100,7 +102,7 @@ Also supports using the `{% else %}` and `{% else if ... %}` tags within an if-b
Fallback content.
{% endif %}
-### autoescape <a id="autoescape" href="#autoescape"></a>
+### autoescape <a name="autoescape" href="#autoescape">#</a>
The `autoescape` tag accepts two controls:
@@ -135,7 +137,7 @@ Will output:
For more information on how the autoescape tag filters variable output, see the [escape filter documentation](filters.md#escape).
-### set <a id="set" href="#set"></a>
+### set <a name="set" href="#set">#</a>
It is also possible to set variables in templates.
@@ -144,7 +146,7 @@ It is also possible to set variables in templates.
<li>{{ num }}</li>
{% endfor %}
-### macro <a id="macro" href="#macro"></a>
+### macro <a name="macro" href="#macro">#</a>
Macros are custom, reusable methods for content-generation that are defined in templates.
@@ -173,7 +175,7 @@ Your output may look like this:
<input type="text" name="lname" id="lname" value="" class="error">
</div>
-### import <a id="import" href="#import"></a>
+### import <a name="import" href="#import">#</a>
The `import` tag is specifically designed for importing macros into your template with a specific context scope. This is very useful for keeping your macros from overriding template context that is being injected by your server-side page generation.
@@ -191,7 +193,7 @@ Assuming the macro `input` exists in _formmacros.html_, you can run the macro by
{# this, however, will NOT output anything because the macro is scoped to the "form" object: #}
{{ input("text", "name") }}
-### filter <a name="filter" href="#filter"></a>
+### filter <a name="filter" href="#filter">#</a>
The `filter` tag allows you to apply a [filter](filters.md) to all final content within the specified `filter` tag.
@@ -203,8 +205,8 @@ The `filter` tag allows you to apply a [filter](filters.md) to all final content
OH HI, PAUL
Hi! My name is Paul!
-<a id="custom-tags" href="#custom-tags"></a>
-## Custom Tags
+Custom Tags <a name="custom-tags" href="#custom-tags">#</a>
+-----------
Swig has support for you to write your own custom tags. For more information, see the [Custom Tags Documentation](custom-tags.md).
Please sign in to comment.
Something went wrong with that request. Please try again.