sergeche / docpad-plugin-menu Goto Github PK

View Code? Open in Web Editor NEW

19.0 5.0 9.0 11 KB

A DocPad plugin for menu generation

CoffeeScript 100.00%

docpad-plugin-menu's Introduction

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 document
false: 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’s title property is used.
menuHidden: boolean. Should current item and its children appear in menu
menuOrder: 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.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.

docpad-plugin-menu's People

Contributors

Stargazers

Watchers

Forkers

mikeumus ofshard kevindice dominics maxlinc pixeleet redcom alexzaporozhets shched

docpad-plugin-menu's Issues

Only including a subset of the generated menu structure

I'm currently evaluating DocPad and came across your plugin and emmet doc sample site. This looks like it works well for a single product documentation site but I have an additional need and I was wondering if this is already a feature I haven't found or something that could be added.

I want to structure my folders under the root with a folder for each product, each product would have subfolders that would be considered topics with the index.html document being the page for the topic. Also in that same topic subfolder I would have additional documents that would show as leafs for the topic.

Something like this:

Product 1
- Topic 1
  - Index.html - (would be page linked to Topic)
  - Topic Page1.html
  - Topic Page2.html
  - Topic Page3.html
- Topic 2
  - Index.html - (would be page linked to Topic)
  - Topic Page1.html
  - Topic Page2.html
  - Topic Page3.html
Product 2
- Topic 1
  - Index.html - (would be page linked to Topic)
  - Topic Page1.html
  - Topic Page2.html
  - Topic Page3.html
- Topic 2
  - Index.html - (would be page linked to Topic)
  - Topic Page1.html
  - Topic Page2.html
  - Topic Page3.html
    etc.

Then in each of the pages within a Product, I'd like to show only the menu items that exist within that Product. I guess in the template you'd have to pass in the second level folder name and limit only urls that are below that.

I hope this makes sense.

no children with optimize = false

when I change the flag optimize to false then the result from generateMenu become flat without any children.

No way to include root index.html document to the menu and keep "optimize: true"-behavior

If optimize option set to true then there is no root index.html document in generated menu structure. But what if I need to include it?

state property doesn't work for index files with optimize = false

I do some console.logs where page is the element of the result of the generateMenu function:
document.url and page.url have the same value: /website/de/index.html
but page.state is false

Skipfiles

For me the skipfiles parameter (set in docpad.coffee) only works if i change item.slug variable in line 102 in menu.pugin.js:

if ((_ref = options.skipFiles) != null ? _ref.test(item.slug) : void 0) {

to item.url :

if ((_ref = options.skipFiles) != null ? _ref.test(item.url) : void 0) {

Support multiple children in one folder

The emmett docs samples are setup like this:

src/
  documents/
    abbreviations/
      index.html.md
      implicit-names/
        index.html.md
      lorem-ipsem/
        index.html.md
      syntax/
        index.html.md
      types/
        index.html.md

I wanted a setup more like this:

src/
  documents/
    abbreviations/
      index.html.md.eco
      implicit-names.html.md.eco
      lorem-ipsem.html.md.eco
      syntax.html.md.eco
      type.html.md.eco

This didn't work. Not only did I not get the desired menu, but the menu partial broke and non of my pages rendered correctly.

Specifically, I would the error:
Rendering the extension "eco" to "html" on "page.html.eco" didn't do anything.

page.html.eco was my layout containing the menu. It renders fine when I use the deeper structure but breaks as soon as I have children without extra folders.