Tweet

Docs /  content

Embedding Code

Assemble has many solutions for embedding code snippets, depending on your needs.

Helpers for Embedding Code

You can use one of Assemble's built-in "code" helpers (from the handlebars-helpers library), or create a custom helper that meets your needs.

Each "code helper" is useful for a different use case. Visit the documentation for each helper to learn more about them.

Embedding Code in Markdown

If you're writing your code in markdown, the easiest way to embed snippets is to use "fenced code blocks", which also allows syntax highlighting. For examples in practice, see this assemble boilerplate for markdown projects, in particular take a look at the code in these templates.

Also see "A Better Markdown Cheatsheet".

Embedding options

Inline Code

Wrap inline snippets of code with a backtick before and after the snippet: code.

For example, <section></section> should be wrapped as "inline".

For example, `<section></section>` should be wrapped as "inline".

Block code "fences"

Use "fences" ``` to block in multiple lines of code:

  
```
options: {
  helpers: 'src/helpers/helper-*.js'
}
```
  

Renders to this:

options: {
  helpers: 'src/helpers/helper-*.js' 
}

Indented code

For code blocks, as an alternative to backticks you may indent several lines of code by at least four spaces.

    // Indent your code like this
    line 1 of code
    line 2 of code
    line 3 of code

Renders to this:

line 1 of code
line 2 of code
line 3 of code

Syntax highlighting

Assemble uses [Marked.js][marked] for processing markdown. "A full-featured markdown parser and compiler, written in javascript. Built for speed". With Marked, you can use GitHub Flavored Markdown or "GFM" "fenced" code blocks to achieve syntax highlighting with your snippets of code.

To activate it, simply add the file extension of the language you want to use directly after the first code "fence", ```js, and syntax highlighting will automatically be applied in the rendered HTML.

For example, to apply syntax highlighting for JavaScript, you add either js or javascript after the first fence:

  
```javascript
grunt.initConfig({
  assemble: {
    options: {
      assets: 'docs/assets',
      data: 'src/data/*.{json,yml}',
      helpers: 'src/custom-helpers.js',
      partials: ['src/partials/**/*.{hbs,md}']
    },
    pages: {
      options: {
        layout: 'default.hbs'
      },
      files: {
        './': ['src/templates/pages/index.hbs']
      }
    }
  }
};
```
  

Which renders to:

grunt.initConfig({
  assemble: {
    options: {
      assets: 'docs/assets',
      data: 'src/data/*.{json,yml}',
      helpers: 'src/custom-helpers.js',
      partials: ['src/partials/**/*.{hbs,md}' ]
    },
    pages: {
      options: {
        layout: 'default.hbs' 
      },
      files: {
        './': ['src/templates/pages/index.hbs' ]
      }
    }
  }
};

Note that whenever you embed handlebars templates and you don't want them to be processed, you do have to escape them with a backslash, like this: {{module-class}}. Don't forget the close tags (I often do)... This is pretty cool because you can embed templates in your examples that should be processed as well. Makes it nice for maintaining documentation.

Embedding Code in HTML

Aside from using the obviously add all of the <pre> tags manually as in your example, or you can use the {{#markdown}}...{{/markdown}} block helper (see Markdown Helpers and the Assemble docs for Markdown ) to wrap sections of markdown inside your HTML:

  
{{#markdown}}
``` js
options: {
  helpers: 'src/helpers/helper-*.js'
}
```
{{/markdown}}
  

See the template for this page →

Find an error? Let us know →