options.ext

options.ext

Specify the file extension to use on dest files. Extensions can be specified at the task and target-levels.

Type: String (optional) Default: .html

Overview

When planning out the strategy for your build targets, templates-overview and data, don't forget to take the ext variable into consideration. ext opens up a few doors by "bending the rules" around how your source files will be compiled or rendered.

In 90% of cases, the ext option will not be needed, and simply using the .hbs file extension on your templates-overview will suffice. However, in scenarios where you are using mixed content, say HTML and markdown with Handelbars templates embedded in one or both formats, you may need to use the ext option to esure that you get the output you need.

Mixed content: Markdown and HTML together

Consider the following scenario:

• Your page content and/or blog posts will be written in markdown format
• You want to embed Handlebars templates in your markdown content for certain types of metadata, such as links, date/time, etc.
• Your page layouts are made from HTML, but they also with embedded with Handlebars templates

• Your end goal is for all of your markdown content to be rendered to HTML in the output.

  and you want your need to compile some markdown files to HTML, and you want to use other markdown files as "includes" or "partials" inside other markdown files, in which case you want the markdown files to be rendered as markdown in the output. You may even want to embed Handlebars templates inside your markdown files to be parsed and compiled.

Extensions map

Whitelisted extensions

As of 11/10/2013, Assemble's extensions map "whitelists" the following extensions:

Handlebars extensions

• handlebar
• handlebars
• hb
• hbars
• hbrs
• hbs
• hbt
• htm
• html
• mustache
• template
• tmpl
• tpl

Markdown extensions

• markd
• markdown
• md

Forcing non-whitelisted extensions

If you need Assemble to process templates in files with an extension that isn't in extensions.yml, you must explicitly define the template engine in the task/target options to force Assemble to process your templates.

So given this example:

assemble: {
  options: {
    engine: "Handlebars"  // case insensitive 
  },
  files: {
    'dist/': ['src/pages/*.snickerdoodle' ]
  }
}

So now that we have defined an engine, Handlebars, Assemble knows to use that engine to process templates with the .snickerdoodle extension. Even better, your templates will also be compiled into delicious Christmas cookies with cinnamon and sugar sprinkled on top.

Example usage

Here are some examples that cover common use cases.

Markdown-to-markdown

If your repo is on GitHub, it's a safe bet you're using markdown format on your READMEs and wikis. Here we're going to show you how to use templates to generate markdown files, so if you work on big projects, or a lot of projects, you can potentially reduce the amount of time you spend updating documentation, changelogs, links, common metadata and so on.

Now, of course there are many ways to accomplish the same goal, this is an example so we're going for simplicity. Here's what we want to accomplish:

• src content written in markdown
• src content contains templates,
• Metadata for templates must come from a single source, say package.json (this is arbitrary, you can use more than one file if you want, .yml format is fine too)
• generated dest files must remain in markdown format. In other words, we want Assemble to process the templates, but not to convert the markdown to HTML.

Here is what we need to do:

Example configuration:

assemble: {
  options: {
    data: 'src/data/readme.yml',
    partials: 'src/content/*.hbs',
    ext: ''  // add the "empty" ext property 
  },
  readme: {
    files: {
      './': ['src/templates/README.md.hbs' ]
    }
  }
}

Our goal here is to tell the assemble task to treat the src markdown files as regular content. In other words we don't want the task to convert the markdown files to HTML, so we use a sort of trick that allows us to write our README content in markdown along with embedded Handlebars templates.

Our goal here is to tell the assemble task.

Here, we tell the assemble task not to use an extension on dest files by leaving ext: '' blank. We do this because our templates have the extenions .md.hbs and assemble only slices off the last extension at build time. So by 1) telling assemble not to add another extension to the rendered templates, and 2) by naming our template files with the .md.hbs extension, we

markdown-to-HTML

Common use cases:

• Blog posts written in markdown, converted to HTML for a live site.
• gh-pages documentation

assemble: {
  options: {
    engine: "Handlebars"  // case insensitive 
  },
  files: {
    'dist/': ['src/pages/*.md.hbs' ]
  }
}

Rendered pages will have the .html extension by default.

---

See the template for this page →