A DocPad plugin that automatically generates menu structure from documents
folder for your web-site.
Installation
Run npm install --save docpad-plugin-menu
command in your DocPad project root.
How it works
This plugin takes a plain list of document files and creates structured menu. The templateData
object of your DocPad config is extended with generateMenu(url)
which takes passed URL (in most cases, the URL of rendered document) and generates menu aginst it. Each menu item contains state
property that holds highlighting state of item.
Possible values:
"current"
: item is a currently viewed document"parent"
: item contains currently viewed documentfalse
: regular item
The best way to output menu is to use partials:
1 - Create menu.html.eco
partial (I’m using Eco templates, but you can use any other):
<% renderMenu = (items) => %>
<ul class="nav">
<% for item in items: %>
<li<% if item.state: %> class="selected"<% end %>>
<% if item.state != 'current': %>
<a href="<%= item.url %>"><%= item.title %></a>
<% else: %>
<strong><%= item.title %></strong>
<% end %>
<% if item.children: %>
<%- renderMenu(item.children) %>
<% end %>
</li>
<% end %>
</ul>
<% end %>
<%= renderMenu @menuItems %>
2 - In your template, invoke menu.html.eco
partial and pass menuItems
context object containing menu state for currently viewed document:
<!doctype html>
<html lang="en">
<head>
<title>Document</title>
</head>
<body>
<nav>
<%- @partial('menu.html.eco', {menuItems: @generateMenu(@document.url)}) %>
</nav>
</body>
</html>
Note that you can use a custom collection by calling the generateMenu function this way:
@generateMenu(@document.url, "myCustomCollection")
For more information about custom collections, please see the Docpad documentation.
Document meta-data
You can supply your document headers with menu-specific meta-data:
menuTitle
: string. Title of menu item. If not defined, document’s title
property is used.menuHidden
: boolean. Should current item and its children appear in menumenuOrder
: number. Order of menu item in its parent. Sorting is ascending.
You can add any menu*
meta-data into your document and its value will be available as menuItem.meta.*
property of menu item. For example, if you add menuFoo: 1
meta-data, you can use its value like this:
<% renderMenu = (items) => %>
<ul class="nav">
<% for item in items: %>
<% if item.meta.foo == '1': %>
<% end %>
<% end %>
</ul>
<% end %>
Plugin configuration
In the DocPad config file, you can add menuOptions
object with the following properties:
optimize
: boolean. Optimize menu structure: items like /about/index.html
will be omitted in favour of parent’s /about/
item. E.g. this option will remove all index.html
file names from generated structure. Default is true
.skipEmpty
: boolean. Removes indermediate items from menu structure that has no content. Default is true
.skipFiles
: regexp. Regular expression to skip files from generated menu structure. If document full url matches this regexp, it will not appear in menu.
Example docpad.coffee
configuration:
docpadConfig = {
plugins:
menu:
menuOptions:
optimize: true
skipEmpty: true
skipFiles: ///\.js|\.scss|\.css/// #regexp are delimited by three forward slashes in coffeescript
}
Other plugin usage examples can be found in Emmet Documentation web-site source.