Pages

Pages are the actual content the user sees. The page you're currently looking at is a markdown page.

Adding Pages

To create new pages, simply add them to the pages folder in content.
Menagerie will look for the following file extensions to generate from:

*.md -> Markdown
*.jinja2, *.html, *.htm -> HTML
*.json, *.jsonc -> JSON Schema
*.xsd, *.xml -> XML Schema
*.yaml, *.yml -> YAML Schema

A Note About Home

When menagerie encounters a page titled 'home', special behaviour occurs:

• The title of the page is set to just the app name, and the "Home -" is omitted
• The navbar icons and app name will lead to that page when clicked

You want to set Out_File to index on this page so your webserver knows to use this page as the landing document.

Page Metadata

Page metadata is data included in the file that tells menagerie how to generate a corresponding HTML document.
The way to describe metadata is different depending on what language you're using

Markdown Metadata

Uses the standard markdown metadata format, create a block at the very top of your document that looks like this:

---
Title: My Page
Sort_Priority: 100
---

# Welcome to my cool page!
...

HTML Metadata

Uses jinja comments ({# #}), create comments near the top of the file that look like this (note the ~ characters):

{#~ Title: My Page ~#}
{#~ Sort-Priority: ~#}

JSON Schema Metadata

Create a top-level key named $docs. Then simply put in keys:

{
    "$docs": {
        "title": "My Page",
        "sort_priority": 100
    }
}

YAML Schema Metadata

Create a top-level dictionary named $docs. Then simply put in the keys:

$docs:
  title: My Schema
  description: My really cool schema
  sort_priority: 100

XML Schema Metadata

Uses xml comments; create comments near the top of the file that look like this (note the ~ characters)

<!--~ Title:My Page ~-->
<!--~ Sort_Priority:100 ~-->
<Myelement>Text</Myelement>
<!-- ... -->

Metadata Reference

Note: These are all case-insensitive

Linking to Pages

You can link to other pages in markdown and html pages by using the route filter and passing in the title of the page

<a href="{{ 'my page'|route }}">Check out my cool page!</a>

[Check out my cool page!]({{ 'my page'|route }})

Referencing Schema Properties

When you want to link to specific schemas properties, you can use the normal route filter and append the path of the property after a hashtag.

[Link to my schema property]({{ "My Schema"|route }}#my-property)

If you don't know the path of the property, go to the page for the schema and click on it; The path should then appear in your URL bar after the # character.

Table of Contents

A table of contents is automatically generated for HTML and Markdown pages.
This can be disabled with the render_toc metadata attribute.

In Markdown

In markdown all headings are put into the table of contents

In HTML

In HTML all headings with an id are put into the table of contents

Images

Images are static files, in order to get the path to put in the src attribute, you can use the static filter. Pass in the path of the files relative to the static folder in content.

<img alt="My cool image" src="{{ 'images/my_image.png'|static }}"/>

![My cool image]({{ 'images/my_image.png'|static }})

Adding Styles to Pages

You can use the styles config option to set a global CSS file to apply to all pages, just pass in the path relative to the static folder.

{
    "styles": {
        "base": "styles/my_base_styles.css",
        "schema": "styles/my_schema_styles.css"
    }
}

You can also specify one for schemas only.

Admonitions

Menagerie also provides a way to make admonitions, which look like this:

To create admonitions, use this syntax:

!!! alert-info "Title"
    Admonition Body Text

You can replace the info with any valid bootstrap alert type. Or you could use your own if you're compiling your own alert variants in SASS.

Grouping Pages

To create groups of pages (dropdowns in the navbar), create folders in the pages folder. For example if I want a dropdown for all of my schemas I might lay out my pages folder like so:

- index.md
- schemas/
    - my_schema.json
    - my_other_schema.xsd

This will create a dropdown named "Schemas" on the navbar.

Group Metadata

Groups can also have metadata. To specify it, create a file called _folder.json in the folder. Then fill this out with the metadata. Groups only allow for title and sort_priority to be set.

Minification

All rendered pages are minified to save on space and network load (this can be disabled in config.json).

Built-In Filters & Globals Reference

In addition to all the built-in jinja filters, menagerie provides some more:

Also, you have access to the settings dictionary, which holds all options from your config.json and some more.
To view these properties, look at Settings.py in the source code.

Extra Settings

Using the extras key in settings allows you to define additional options to insert into pages.
For example, this sentence is actually a property in extras.

{
    "extras": {
        "extras_explanation": "For example, this sentence is actually a property in extras."
    }
}

... into pages.  
{{ settings['extras']['extras_explanation'] }}

This can be useful for stuff like author names, copyright, and other data that is used in multiple places and changes often.