Skip to content
This repository has been archived by the owner on May 31, 2020. It is now read-only.

Commit

Permalink
Update tags.md.
Browse files Browse the repository at this point in the history 
- Add documentation for url_encode, statics?, and statics tags.

- Hard-wrap the document for easier reading.

- Add an automatic TOC entry for generated HTML.
  • Loading branch information
Noel Cower committed Aug 8, 2012
1 parent c5f85b4 commit 0a9841b
Showing 1 changed file with 174 additions and 59 deletions.
233 changes: 174 additions & 59 deletions tags.md
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,96 @@
# Templates
Templates
================================================================================

First off, OakTree uses [Mustache] for templates. So, go read its documentation then you can come on back and continue reading this. Alright, now that we've got that out of the way, let's talk about where these go.
First off, OakTree uses [Mustache] for templates. So, go read its documentation
then you can come on back and continue reading this. Alright, now that we've
got that out of the way, let's talk about where these go.

All of your .mustache template files must be placed under `BLOG_ROOT/templates`. It's pretty simple, don't over-think this. Now, there is only one required template: `blog.mustache`. This is the template `Blog` loads when OakTree generates its HTML, so it's pretty important. This is your blog's index, basically.
All of your .mustache template files must be placed under
`BLOG_ROOT/templates`. It's pretty simple, don't over-think this. Now, there is
only one required template: `blog.mustache`. This is the template `Blog` loads
when OakTree generates its HTML, so it's pretty important. This is your blog's
index, basically.

In `blog.mustache`, you can do whatever you want from there. That said, there are a number of tags that're worth knowing. The tags below are all separated by context, and there are only three contexts: Blog, Post, and PostArchive. There's not a lot there because this is purposefully simple.
In `blog.mustache`, you can do whatever you want from there. That said, there
are a number of tags that're worth knowing. The tags below are all separated by
context, and there are only three contexts: Blog, Post, and PostArchive.
There's not a lot there because this is purposefully simple.

It's worth keeping in mind, however, that the `Blog` class renders templates in three different modes: archive, single, and home. These are fairly simply to understand, but documentation follows nonetheless.
It's worth keeping in mind, however, that the `Blog` class renders templates in
three different modes: archive, single, and home. These are fairly simply to
understand, but documentation follows nonetheless.

[Mustache]: http://mustache.github.com

------------------------------------------------------------------------------
1. TOC Goes Here
{:toc}


# Blog Modes
Blog Modes
================================================================================

Each blog mode differs by the way it composes pages and which tags are functional. For instance, some tags that work in archive mode made not work in single and home mode.
Each blog mode differs by the way it composes pages and which tags are
functional. For instance, some tags that work in archive mode made not work in
single and home mode.

## Archive

archive mode pages render all posts from each month. Empty months are not represented and do not have any HTML generated. To explain this in a boring and slightly clearer manner, this means that an archive page's HTML will contain all posts from only one month.
Archive
--------------------------------------------------------------------------------

## Single
Archive mode pages render all posts from each month. Empty months are not
represented and do not have any HTML generated. To explain this in a boring and
slightly clearer manner, this means that an archive page's HTML will contain
all posts from only one month.

Pages in single mode is composed of a single post. In other words, a single mode page is just looking at one post.
Single
--------------------------------------------------------------------------------

## Home
Pages in single mode is composed of a single post. In other words, a single
mode page is just looking at one post.

Each page in home mode represents a chronological series of paginated posts. Pages only contain however many posts you've specified in your `blog_spec`'s `posts_per_page` attribute. Ideally, you should not generate more than the index when in `home` mode, as synchronizing a large body of posts like this would be fairly painful.
Statics
--------------------------------------------------------------------------------

Home mode has no special tags, though it lacks access to both archive and single mode tags.
Pages in static mode are disconnected from all other pages. They're essentially
articles that sit outside the normal flow of the blog.

Home
--------------------------------------------------------------------------------

------------------------------------------------------------------------------
Each page in home mode represents a chronological series of paginated posts.
Pages only contain however many posts you've specified in your `blog_spec`'s
`posts_per_page` attribute. Ideally, you should not generate more than the
index when in `home` mode, as synchronizing a large body of posts like this
would be fairly painful.

Home mode has no special tags, though it lacks access to both archive and
single mode tags.

# Tags by Context

## Blog Context Tags


Tags by Context
================================================================================

What follows is a list of all tags by their context (not mode). Contexts are
the upper-most object currently contributing tags to the template. The blog
context is always the root, while further contexts are typically posts and
archives.


Blog Context Tags
--------------------------------------------------------------------------------

### General Tags

General tags provide you with some information about the blog itself or offer some functionality that isn't specific to a particular mode.
General tags provide you with some information about the blog itself or offer
some functionality that isn't specific to a particular mode.

#### `local_path`

This tag is mainly for use by OakTree internally, but you could also use it for debugging if you were testing out something or other. It just emits the absolute path of the file currently being generated.
This tag is mainly for use by OakTree internally, but you could also use it for
debugging if you were testing out something or other. It just emits the
absolute path of the file currently being generated.

#### `blog_title`

Expand All @@ -56,51 +102,90 @@ Emits the blog author, obviously.

#### `blog_description`

This is whatever you put in your `blog_spec`'s `description` attribute. Your best use of this is probably metadata.
This is whatever you put in your `blog_spec`'s `description` attribute. Your
best use of this is probably metadata.

#### `blog_url`

This is the `base_url` attribute from your `blog_spec`. Why the different name? I don't know, let's blame the tides or something. This URL shouldn't have a trailing forward slash unless you went and put one in the `blog_spec` (in which case you shouldn't have).
This is the `base_url` attribute from your `blog_spec`. Why the different name?
I don't know, let's blame the tides or something. This URL shouldn't have a
trailing forward slash unless you went and put one in the `blog_spec` (in which
case you shouldn't have).

#### `today`

This is a lambda that takes a format string and emits the current date and time as rendered by `DateTime#strftime`. For example, `{{#today}}%Y %B %-d{{/today}}` renders `2012 February 5` (at least at the time of this writing).
This is a lambda that takes a format string and emits the current date and time
as rendered by `DateTime#strftime`. For example, `{{#today}}%Y %B
%-d{{/today}}` renders `2012 February 5` (at least at the time of this writing).

#### `url_encode`

Anything wrapped in this tag will be encoded for placement in a URL. For
example:

{{#url_encode}}{{permalink}}{{/url_encode}}

This will output the permalink encoded for use in a URL.

#### `statics`

This will iterate over all statics currently in the blog. This is accessible
from all contexts and modes and will always provide the same content during
generation.

If you choose to provide statics via a menu visible on all pages, this is a good
way to do it. Keep in mind, however, that this is output on _all_ pages of the
blog, so it can quickly add up if you use many static pages.

In such a case, it may be worth looking into adding a new mode to OakTree.



------------------------------------------------------------------------------

### Page Tags

Page tags tell you something about the page. Use them wisely.

#### `archive?`, `single?`, and `home?`
#### `archive?`, `single?`, `statics?`, and `home?`

These are section tags that you can use to render content differently between archive, single, and home pages.
These are section tags that you can use to render content differently between
archive, single, statics, and home pages.

#### `pages`, `page`

`pages` emits the total number of pages for the current mode. You probably don't need to use this for anything. `page` emits the current page number which, again, is probably not all that useful.
`pages` emits the total number of pages for the current mode. You probably
don't need to use this for anything. `page` emits the current page number
which, again, is probably not all that useful.

#### `paged?`

This section tag tells whether there are next or previous pages. This is only true if there's one page.
This section tag tells whether there are next or previous pages. This is only
true if there's one page.

#### `has_next?` and `has_previous?`

Sectional tags to determine if there are next or previous pages.
Sectional tags to determine if there are next or previous pages. These are
undefined for static pages.

#### `next_url` and `previous_url`

Emits URLs for the next and previous pages respectively.
Emits URLs for the next and previous pages respectively. These are undefined for
static pages.



------------------------------------------------------------------------------

### Post Tags

These tags allow you to access the current set of posts or a single post, as well as a few other things. All post tags provide you with a `Post` context when available.
These tags allow you to access the current set of posts or a single post, be it
static or chained, as well as a few other things. All post tags provide you with
a `Post` context when available.

#### `posts`

A section tag providing access to all posts on the current page. You can use this to render blog posts. The following example would render all posts on the given page uniformly:
A section tag providing access to all posts on the current page. You can use
this to render blog posts. The following example would render all posts on the
given page uniformly:

{{#posts}}
<article>
Expand All @@ -111,23 +196,29 @@ A section tag providing access to all posts on the current page. You can use thi
</article>
{{/posts}}

#### `post` (single only)
#### `post` (single and statics only)

Section tag to access the current post. This only works in single mode. You may also want to read the tags available in a post context.
Section tag to access the current post. This only works in single mode. You may
also want to read the tags available in a post context.

#### `next_post` and `previous_post` (single only)

These section tags are provided in case you want to pull something from the context of either the next or previous posts in line. They only work in single mode.
These section tags are provided in case you want to pull something from the
context of either the next or previous posts in line. They only work in single
mode.



------------------------------------------------------------------------------

### Archive Tags

Archive tags provide access to `PostArchive` contexts. Archive tags have fairly limited utility.
Archive tags provide access to `PostArchive` contexts. Archive tags have fairly
limited utility.

#### `archives`

This section tag provides access to all `PostArchive` contexts from newest to oldest. It can be used to render links to all archive pages, for example:
This section tag provides access to all `PostArchive` contexts from newest to
oldest. It can be used to render links to all archive pages, for example:

<ul>
{{#archives}}
Expand Down Expand Up @@ -156,84 +247,108 @@ Which might produce something like the following:

#### `archive` (archive only)

A section tag that provides access to the page's current `PostArchive` context when in archive mode.
A section tag that provides access to the page's current `PostArchive` context
when in archive mode.

#### `next_archive` and `previous_archive` (archive only)

Section tags that provide access to the next (newer) and previous (older) `PostArchive` contexts.
Section tags that provide access to the next (newer) and previous (older)
`PostArchive` contexts.

#### `archive_date` (archive only)

A lambda that formats the current archive's date (the first day of the month for the `PostArchive` context) using `DateTime#strftime`. Works the same as the `today` tag.
A lambda that formats the current archive's date (the first day of the month
for the `PostArchive` context) using `DateTime#strftime`. Works the same as the
`today` tag.


------------------------------------------------------------------------------


## Post Context Tags
Post Context Tags
--------------------------------------------------------------------------------

There are no particularly special categories of tag under Post since they're all fairly specific to the post to start.
There are no particularly special categories of tag under Post since they're
all fairly specific to the post to start.

#### `title`

The post's title.

#### `url`

The post's URL. If the post has a source link, `url` emits the source link, otherwise it emits the post's permalink. If you need to determine which is which, use the `source_link?` tag.
The post's URL. If the post has a source link, `url` emits the source link,
otherwise it emits the post's permalink. If you need to determine which is
which, use the `source_link?` tag.

#### `permalink`

Emits a permanent link to this file (or at least as permanent as you can hope a link to a file is). This always points directly to the post.
Emits a permanent link to this file (or at least as permanent as you can hope a
link to a file is). This always points directly to the post.

#### `source_link`

This emits the post's source link, which is specified with the `link` attribute in your post file.
This emits the post's source link, which is specified with the `link` attribute
in your post file.

#### `source_link?`

Section tag to determine if there is a source link.

#### `content`

Provides the HTML content of the post. You should wrap this in three curly braces rather than the usual two so Mustache doesn't reformat it. That is, you want to use `{{{content}}}`.
Provides the HTML content of the post. You should wrap this in three curly
braces rather than the usual two so Mustache doesn't reformat it. That is, you
want to use `{{{content}}}`.

#### `time`

This lambda functions the same as the above `today` tag, but emits the formatted time of the post.
This lambda functions the same as the above `today` tag, but emits the
formatted time of the post.

#### `public_path`

Emits the public path for this post. This is only really useful for debugging, since it points to the local file.
Emits the public path for this post. This is only really useful for debugging,
since it points to the local file.

#### `slug`

If for some reason you need access to the post slug, this tag provides it.


------------------------------------------------------------------------------


## PostArchive Context Tags
PostArchive Context Tags
--------------------------------------------------------------------------------

As mentioned above, archive tags generally have little utility. They are useful only when rendering archive mode pages and if you want to provide links to all archives.
As mentioned above, archive tags generally have little utility. They are useful
only when rendering archive mode pages and if you want to provide links to all
archives.

#### `year` and `month`

Both of these tags provide the raw year and month numbers for the archive. Unlike other date/time tags, these are not lambdas and do not provide specially formatted output.
Both of these tags provide the raw year and month numbers for the archive.
Unlike other date/time tags, these are not lambdas and do not provide specially
formatted output.

#### `date`

This is a lambda that formats the `PostArchive`'s date (the first day of the month and year for this context). It works the same as the `today` tag and other formatted date/time tags above.
This is a lambda that formats the `PostArchive`'s date (the first day of the
month and year for this context). It works the same as the `today` tag and
other formatted date/time tags above.

#### `permalink`

The `permalink` tag emits a permanent link to the archive page for this `PostArchive` context.
The `permalink` tag emits a permanent link to the archive page for this
`PostArchive` context.

#### `open?`

Sectional tag to determine if this is the current `PostArchive` context being rendered by the `Blog`. You might use this to de-link or highlight the current archive in a list of archive pages.
Sectional tag to determine if this is the current `PostArchive` context being
rendered by the `Blog`. You might use this to de-link or highlight the current
archive in a list of archive pages.

#### `next_archive` and `previous_archive`

These tags both provide access to archives that follow/precede the current `PostArchive` context. These override the `next_archive` and `previous_archive` tags provided by the `Blog` context above when used in a `PostArchive` context.
These tags both provide access to archives that follow/precede the current
`PostArchive` context. These override the `next_archive` and `previous_archive`
tags provided by the `Blog` context above when used in a `PostArchive` context.

0 comments on commit 0a9841b

Please sign in to comment.