Metadata-Version: 1.0
Name: brace-tags
Version: 1.0.9
Summary: The simplest static site generator
Home-page: UNKNOWN
Author: Cole Krumbholz, Lauri Hynynen
Author-email: team@brace.io
License: LICENSE
Description: Brace Tags
        ==========
        
        > The simplest static site generator
        
        Brace 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 101
        
        You can use Brace Tags to build a multi-page static website without
        duplicating navigation or footer code. Here's generally how it works:
        
        1. Find duplicated code snippets in your HTML files. Extract them into separate
        files called "partials".
        
        2. Replace each duplicated code snippet with a special placeholder tag. The tag
        looks like: `{% include mypartial.html %}`. This is where the content from a
        partial 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 website
        
        Here's a simple multi-page website with `index.html` and `about.html` files. We
        can 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's
        currently being generated. You can use this, for example, to highlight the
        current 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 Tags
        
        Brace 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 Brace
        Tags needs to install the `tags` command line script.)
        
        Brace has one external dependency, `watchdog` which is only required if you want
        to use Brace to monitor a folder for changes, and recompile your site on the
        fly. Before using the `--watch` option you'll need to install `watchdog` with
        `sudo easy_install watchdog`.
        
        
        ## Using Brace Tags
        
        Tags has two commands, the `build` command and the `serve` command. Build is
        used to generate a site from a source folder.
        
            tags build
        
        By default, Brace Tags compiles all the .html files in your site. Tags places
        the generated site in the `_site` folder, and ignores those files during future
        builds. 
        
        Once built, the `serve` command will start a local webserver that you can use
        to view the website locally with your browser. This is for testing only.
        
            tags serve
        
        For more options and explanation, check out the help:
        
            tags --help
        
        ## Hosting your static site
        
        Once you've generated a static site with Brace Tags, you can deploy it to any
        static 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 Tags
        
        If you're a python programmer, you can add your own tags to implement custom
        functionality 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 a
        corresponding tag function. If the function exists, it is called and the result
        is substituted in the output.
        
        In the `/tags/tags.py` file you'll find a function for each template tag. Add
        your custom tag functions to that file. They should look something like this:
        
            lang = TemplateLanguage()
        
            @lang.add_tag
            def print3x(style, body=u'', context={}):
                ''' A tag that appends 3 copies of its body '''
                result = body + body + body
                if style == "bold":
                    result = u'<b>' + result + u'</b>'
                return result
        
        The 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 a
        dictionary containing contextual data passed in by the generator. By default,
        context includes a `filename` key whose value is the file currently being
        generated.
        
        
        You can also define tags that accept a variable argument list like so:
        
            @lang.add_tag
            def whatever(*args, **kwargs):
                return str(len(args))
        
        
        When called, the `*args` parameter will contain the variable argument list, and
        the `body` and `context` keyword args will be in the `**kwargs` dictionary.
        
        ### Using your modified version of Brace Tags
        
        You can install your fork of Tags by first uninstalling the stock version...
        
            pip uninstall brace-tags
        
        And then installing your modified version:
        
            pip install -e path/to/your/brace-tags/folder
        
        You don't need to reinstall this package after making changes. The package will
        stay up-to-date automatically.
        
        
        ## Compatibility
        
        Works with python 2.6, 2.7 and now 3.3 thanks to pyarnold.
        
        
        
Platform: UNKNOWN
