Getting Started with metalsmith-wikify

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

I wrote this plugin to replace an aging Confluence Wiki server that I had running for documentation purposes. While Confluence was one of my favorite wiki engines, it was overkill for a single-user documentation website such as this one.

Metalsmith-Wikify Features

  • Flatten a hierarchical directory structure
  • Build parent/child hierarchy for navigation and breadcrumbs
  • Access a multi-level menu system
  • Useful shortcodes like children and page
  • Custom templates for partials

Since this plugin emulates a wiki, your content must abide by the wiki-rules for page-naming: that is, no two pages can have the same name. However, it is intended that within each directory level there is a page index.md. Metalsmith-Wikify will change the name of each of those to that of the containing directory.

Installation

Soon to be in npm. For now use github.

> npm install --save-dev dmccuskey/metalsmith-wikify

Usage

var
  Metalsmith = require('metalsmith'),
  wikify = require('metalsmith-wikify');

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

Parameters

removeExtension

boolean, true/false (optional) (default false)

Will make nicer looking URLs by removing the .html extension.

The webserver config will need to be modified to support this. The nginx config for this site is in the repo as a reference.

Shortcodes

These shortcodes are available within content pages.

children

Displays the children of the current page.

[children depth=1 excerpt=true style=h4]

Parameters

excerpt (boolean, optional) defaults to false

Specifies whether to show page excert.

depth (integer, optional) defaults to 1

Specifies how many levels of children to display.

style (string, optional) defaults to 'h3'

Specifies the header-level to use when creating children html.

all (boolean, optional) defaults to false

Specifies to show "all" children, which is level 99. it overrides depth.

Excerpt funcitionality requires metalsmith-super-excerpt or similar.

page

Creates a link to another page in the site. The resulting link will honor the value for removeExtension.

[page <page name>.html]

Parameters

<page name> (string, required)

The page name should include the extension, even if removeExtension is set to true.

Example

[page lua-corovel.html]

If the page name isn't found, the link will display the text !! file not found !!.

tip

Displays a content block inside of a box with a thumbs-up icon. There is an optional parameter title.

[tip]<your content>[/tip]

[tip title=<title>]<your content>[/tip]

Example

[tip]May the luck of the Irish be on your side ![/tip]

Result

May the luck of the Irish be on your side !

Example

[tip title=Hello-World]May the luck of the Irish be on your side ![/tip]

Result

Hello-World
May the luck of the Irish be on your side !

note

Displays a content block inside of a box with an Info icon. There is an optional parameter title.

[note]<your content>[/note]

[note title=<title>]<your content>[/note]

Example

[note]Keep on looking for buried treasure.[/note]

Result

Keep on looking for buried treasure.

Example

[note title=Important-Note]Keep on looking for buried treasure.[/note]

Result

Important-Note
Keep on looking for buried treasure.

warning

Displays a content block inside of a box with an Exclamation icon. There is an optional parameter title.

[warning]<your content>[/warning]

[warning title=<title>]<your content>[/warning]

Example

[warning]An improperly charged battery will go dead.[/warning]

Result

An improperly charged battery will go dead

Example

[warning title=Shocking-Truth]An improperly charged battery will go dead[/warning]

Result

Shocking-Truth
An improperly charged battery will go dead

danger

Displays a content block inside of a box with an X icon. There is an optional parameter title.

[danger]<your content>[/danger]

[danger title=<title>]<your content>[/danger]

Example

[danger]Bad things will happen if you join the Empire[/danger]

Result

Bad things will happen if you join the Empire

Example

[danger title=Use-The-Force]Bad things will happen if you join the Empire[/danger]

Result

Use-The-Force
Bad things will happen if you join the Empire