Querying Pages

Queries allow to to select and save groups of pages or calculate values based on your pages' metadata.

The acetate.query function takes 5 arguments.

  1. name - the unique name of this query. You will use this to access query results in your template.
  2. filter - filter all pages by either a glob pattern like **/* or a function that received a page as an argument and returns a boolean. The function syntax is identical to Array.filter()
  3. map - Iterate over results from the filter and create a new array of results. The function is identical to Array.map()
  4. reduce - Iterate over the array of results from the map function and return a new value. This funciton is eqivilant to the callback in Array.reduce()
  5. initial - The initial value to pass into the reduce function.

Example: Dynamically Generated Navigation

module.exports = function (acetate) {
  // ...

    // create a new query called `doc_nav`

    // get all pages in the documentation folder

    // the map function extracts values from each page
    function map (page) {
      return {
        topic: page.topic,
        order: page.order,
        url: page.url,
        title: page.navTitle || page.title

    // the reduce function will take each 'page' and insert it
    // into the navigation for that topic and sort topics in order
    function reduce (nav, page) {
      let section = _.find(nav, {name: page.topic})

      if (section) {
        section.pages = _.sortBy(section.pages, 'order');
      } else {
          name: page.topic,
          pages: [ page ]

      return _.sortBy(nav, function (group) {
        var order = ['Basic', 'Advanced', 'Integrations', 'Modes', 'Misc.'];
        return order.indexOf(group.name);

    // start with an empty array

  // ...

Once you have saved your query, you can access the final value under queries.name in your templates.

  {% for section in queries.doc_nav %}
      <h4>{{ section.name }}</h4>
        {% for page in section.pages %}
        <li>{% link page.url, page.title %}</li>
        {% endfor %}
  {% endfor %}

Edit this Page on GitHub