Getting Started with metalsmith-super-excerpt

This is a short overview about the capabilities of metalsmith-super-excerpt.

Most other excerpt libraries process WordPress-like excerpts, searching for the string <!-- more --> in the document and grabbing everything before that tag. This library processes Confluence-like excerpts, where any text in the entire document can be used for the excerpt.

This plugin also has named excerpts which can be referenced in other pages and templates enabling you to reuse site content anywhere !

Installation

Soon to be in npm. For now use github.

> npm install --save-dev dmccuskey/metalsmith-super-excerpt

Usage

var
  Metalsmith = require('metalsmith'),
  superExcerpt = require('metalsmith-super-excerpt');

Metalsmith(__dirname)
    .use(markdown())
    .use(superExcerpt({
        clean: true,
    })
    .use(templates())
    .destination('./dist')
    .build(function(err){
        if (err) throw err;
    });

Shortcodes

Upon downloading Super-Excerpt, via simple shortcodes, you now wield the power to:

  • create page-level excerpts, local to the page
  • create named excerpts, which can be shared among all pages

Page-level Excerpts

Use an excerpt shortcode to enclose the desired content block, even spanning multiple lines. There is an optional parameter whether or not to show the excerpt on the page.

[excerpt]<your content here>[/excerpt]

[excerpt hidden=true]<your content here>[/excerpt]

Using Content

Now you can access the excerpt content inside of your templates. To do this, use markup appropriate for your template system, here it is shown in Swig:

{{ excerpt }}

It's possible that you will need to tell swig the content is safe by using the filter safe:

{{ excerpt | safe }}

Named-Excerpts

Using named-excerpts you can share any content between pages or use it in templates. To do this, use the same excerpt shortcode as before but supply a name in the excerpt tag like so:

[excerpt name=super-excerpt-overview]<your content here>[/excerpt]

This will store the content in a global excerpt table which is located on the Metalsmith metadata table.

Using Content

Now you can access that excerpt in other pages and templates by using the insertExcerpt shortcode.

Content Pages

[insertExcerpt name=super-excerpt-overview]

Templates

This example is for Swig templates:

{{ insertExcerpt['super-excerpt-overview'] }}

Again, you might need to let Swig know that the content is safe by using the filter safe:

{{ insertExcerpt['super-excerpt-overview'] | safe }}

Use Cases

You could use this functionality to document software classes and their inheritance. A superclass could wrap its API in a named-excerpt, and any documentation pages for each subclass page could borrow that content.

The important question is, "How will you use it ?"