docpad-plugin-menu
v3.0.0
Published
Automatically generates menu from documents folder
Downloads
32
Maintainers
serge.cheReadme
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):
<!-- Define `renderMenu` partial -->
<% renderMenu = (items) => %>
<ul class="nav">
<% for item in items: %>
<!-- Highlight menu item if its `item.state` is not false -->
<li<% if item.state: %> class="selected"<% end %>>
<!-- Remove link if we’re currently viewing this document -->
<% if item.state != 'current': %>
<a href="<%= item.url %>"><%= item.title %></a>
<% else: %>
<strong><%= item.title %></strong>
<% end %>
<!-- Render submenu if item has children -->
<% if item.children: %>
<%- renderMenu(item.children) %>
<% end %>
</li>
<% end %>
</ul>
<% end %>
<!-- Run `renderMenu` partial aginst passed `menuItems` meta-data -->
<%= 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’stitleproperty 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': %>
<!-- Do something if menuFoo equals '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.htmlwill be omitted in favour of parent’s/about/item. E.g. this option will remove allindex.htmlfile names from generated structure. Default istrue.skipEmpty: boolean. Removes indermediate items from menu structure that has no content. Default istrue.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.