Package: brace-tags
Brace Tags==========> The simplest static site generatorBrace Tags is a static site generator focused on simplicity. It does one thing:solves the problem of having to repeat the same HTML code on several web pages.(In other words, it provides "partials")The template language provided by Brace Tags has only two tags, `include` and`is`.## Static site generation 101You can use Brace Tags to build a multi-page static website withoutduplicating navigation or footer code. Here's generally how it works:1. Find duplicated code snippets in your HTML files. Extract them into separatefiles called "partials".2. Replace each duplicated code snippet with a special placeholder tag. The taglooks like: `{% include mypartial.html %}`. This is where the content from apartial will be injected.3. Run the `tags build` command to assemble the website from your source code.You can put the generated site online using any static site hosting provider.## An example Brace Tags websiteHere's a simple multi-page website with `index.html` and `about.html` files. Wecan add the main navigation into each page with the `include` tag.index.html:<html><body>{% include nav.html %}  <!-- include the nav partial -->Welcome to Brace Tags!</body></html>about.html:<html><body>{% include nav.html %}Brace Tags is very simple!</body></html>The `is` tag is used to change the content of a partial based on the file that'scurrently being generated. You can use this, for example, to highlight thecurrent page in the nav partial.nav.html:<ul><li><a href="/" {% is index.html %}class="active"{% endis %}>home</a></li><li><a href="/about.html" {% is about.html %}class="active"{% endis %}>about</a></li></ul>Note: you'll need to define CSS styles separately to take advantage of the`active` class attribute used above.## Installing Brace TagsBrace Tags requires Python. Many computers today come with Python pre-installed,including all macbooks. If you have Python, you can install Brace Tags with`easy_install` by opening up your terminal and typing in:sudo easy_install brace-tags(The sudo part will ask you to provide a password. It's required because BraceTags needs to install the `tags` command line script.)Brace has one external dependency, `watchdog` which is only required if you wantto use Brace to monitor a folder for changes, and recompile your site on thefly. Before using the `--watch` option you'll need to install `watchdog` with`sudo easy_install watchdog`.## Using Brace TagsTags has two commands, the `build` command and the `serve` command. Build isused to generate a site from a source folder.tags buildBy default, Brace Tags compiles all the .html files in your site. Tags placesthe generated site in the `_site` folder, and ignores those files during futurebuilds.Once built, the `serve` command will start a local webserver that you can useto view the website locally with your browser. This is for testing only.tags serveFor more options and explanation, check out the help:tags --help## Hosting your static siteOnce you've generated a static site with Brace Tags, you can deploy it to anystatic site host. Github pages and S3 are just a couple of the many options.Of course we'd love for you host your site with us, on[Brace](http://brace.io)!## Advanced: Extending Brace TagsIf you're a python programmer, you can add your own tags to implement customfunctionality on top of Brace Tags.Custom tags should look like this:{% mytag argument1 argument2 %}Optionally, a tag can have a body, like this:{% mytag %}Tag Body{% endmytag %}Each time Brace Tags encounters a tag in an input file it checks for acorresponding tag function. If the function exists, it is called and the resultis substituted in the output.In the `/tags/tags.py` file you'll find a function for each template tag. Addyour custom tag functions to that file. They should look something like this:lang = TemplateLanguage()@lang.add_tagdef print3x(style, body=u'', context={}):''' A tag that appends 3 copies of its body '''result = body + body + bodyif style == "bold":result = u'<b>' + result + u'</b>'return resultThe above function creates a print3x tag that can be used like this:{% print3x bold %}<h1> ROBOTS, MAKE MY HTML! </h1>{% endprint3x %}When adding a new tag function, here are some things you should know:- The `add_tag` decorator adds the tag function to the template language.- The tag's name is taken from the function's name. Optionally you can use the`add_tag_with_name` decorator to supply a tag name.- The positional arguments of the function define the tag's required arguments.In the above case, the print3x tag requires one argument, a `style`.- If you specify a `body` keyword argument, then the tag will require a body.The body is the content between the opening tag and an end tag.- All tag functions must accept a `context` keyword argument. This is adictionary containing contextual data passed in by the generator. By default,context includes a `filename` key whose value is the file currently beinggenerated.You can also define tags that accept a variable argument list like so:@lang.add_tagdef whatever(*args, **kwargs):return str(len(args))When called, the `*args` parameter will contain the variable argument list, andthe `body` and `context` keyword args will be in the `**kwargs` dictionary.### Using your modified version of Brace TagsYou can install your fork of Tags by first uninstalling the stock version...pip uninstall brace-tagsAnd then installing your modified version:pip install -e path/to/your/brace-tags/folderYou don't need to reinstall this package after making changes. The package willstay up-to-date automatically.## CompatibilityWorks with python 2.6, 2.7 and now 3.3 thanks to pyarnold.