Clone this wiki locally
All materials that aid the communication of information are considered presentational elements. Layouts are used to render the content and the assets used form the presentation (images, CSS, JS and also LESS, CoffeeScript that compiles to CSS, JS) comes under this definition. Presentational elements must be placed inside the
Layouts define how content must be presented. For each page request, Punch passes the matching layout and content to the template engine, which outputs the rendered page. The layouts must be written using the enabled template engine format.
There are 3 types of layouts in Punch:
- Page layouts
- Section layouts
- Partial layouts
You can define a layout of its own for each page in the site. The layout for
/index would be
templates/index.mustache. Similarly, layout for
/about/press.html would be
Note that page layout must be defined in the same level as the requested page. For example, if someone requests for
/about/index.html; it won't be rendered using the
You will notice, on most occasions entire sections of a site carry the same layout. For example, all blog posts use a common layout. All product pages use a common layout.
Section layouts can be used to define such common layouts. A section layout must be named as
_layout.mustache and must be placed inside the directory that defines the section. For example, if you define a section layout in
templates/blog/_layout.mustache; it will be used to render pages such as
Section layouts are inherited. For a page request such as
/blog/2012/09/10-sample-post we don't have a explicit page layout or a section layout defined for the level. However, it will use the closest section layout it can find in its ancestors; which would be
templates/_layout.mustache is the top-most section layout that can be defined and it's considered as the main layout of the site. If all pages in your site uses a common layout, you can define only the
templates/_layout.mustache. Then, every page will be rendered using this layout.
You can extract the parts that are repeated in multiple layouts into partials. Partial layout names must start with an underscore (eg.
_header.mustache). You can render a partial layout inside a page or section layout using the following syntax.
Similar to section layouts, partial layouts can also be inherited.
Defining layouts for specific formats
For some request formats, you need to present a different output than the default. For example, if you define a layout named
templates/_layout.rss.mustache, it will be used to serve requests expecting a response in RSS format.
In Punch, assets such as JS, CSS and images must also be placed inside the
templates directory. However, within the
templates directory, you can organize them in any way you want. Punch can also pre-process and bundle the assets for you.