YAML configuration

Configure your site metadata, rendering configuration and such using YAML configuration. Create a foo.yaml alongside foo.md or foo/ folder, and those settings apply only to that route. The YAML structure is the same as your Markdown frontmatter, and vice-versa. Settings in the YAML frontmatter apply onto that Markdown route only; whereas settings in an individual .yaml file apply to that entire sub-route tree. Emanote does a deep-merge of the parent YAML configurations, so you can have children override only what’s necessary. This is sometimes known as “data cascade”. The final merged YAML structure is passed to the HTML templates, of which you have full rendering control over.

Notice how this page’s sidebar colorscheme has changed to green? View the source of this page to see the magic involved. That CSS greenery you just saw too comes from YAML.

Examples

Links to this page
  • Uplink tree

    This behavior can be configured. To turn off the implicit folder nodes, set to false the corresponding flag in your configuration as shown here:

  • Syntax Highlighting

    In order to enable syntax highlighting, you must use a client-side JavaScript highlighter, such as highlight.js by adding it to page.headHtml of YAML configuration (if adding to all or multiple routes) or Markdown frontmatter (if adding to a single route). Emanote already provides a snippet, so you may directly include the following in your index.yaml (assuming you are enabling it on all routes):

  • Sidebar
    If the order frontmatter metadata exists, use that as the primary sort key.
    The sidebar tree is collapsed by default. But this can be disabled by setting template.sidebar.collapsed to false in YAML configuration
  • Org Mode ✍️
    While #+TITLE is recognized, other metadata are not recognized (yet). Therefore you must store file-associated metadata in a separate YAML file.
  • Obsidian-style queries

    This will use the date frontmatter metadata to sort the results, as well as display the date alongside it. A live demo of that snippet above is presented below:

  • Neuron-like layout

    Emanote comes with two built-in HTML template layouts. The default layout is called “book”, but you may select the “note” layout (which mimics Neuron) by adding the following to your index.yaml,

  • Migrating from neuron
    If you have a head.html, transfer its contents to index.yaml (see example and explanation)
    YAML based configuration at per-route level
  • Mermaid Diagrams

    To enable this, add the following to your page.bodyHtml, either in frontmatter or index.yaml (see YAML configuration):

  • Math
    Add the following to your page.headHtml, either in frontmatter or index.yaml (see YAML configuration)
  • Markdown ✍️

    Add Twitter-like hashtags anywhere in Markdown file. They can also be added to the YAML frontmatter. Hash tags can also be “hierarchical”, for instance: #emanote/syntax/demo

  • Layer system

    Emanote implicitly includes what is known as the “default” layer. Its contents can be seen here. This layer contains HTML Templates, index.yaml and other default assets, like the logo, favicon and fonts. When you run emanote -L /your/notebook run, your notebook is overlaid on top of this default layer. What this means, in effect, is that you override just about any file in the default layer, such the HTML content of HTML Templates, in your own notebook directory. As an example, see template/hooks of this documentation notbook.

    The default merge semantic is to replace with the file on the right layer. For some file types, special merge semantic applies. For example, YAML files are merged by deep merge, not file-level replacement. This is what allows you to create index.yaml that overrides only a subset of the default configuration.

  • JavaScript behaviours

    Improve your Emanote website using custom JavaScript code. Emanote provides built behaviours that can be accessed in js metadata key (see YAML configuration).

  • HTML Templates

    Emanote includes two builtin layouts, called book (the default) and `note`, but you can also write your own HTML layout from scratch, as long as you specify that template in YAML configuration for the notes in question. For eg., templates/home.tpl is how https://srid.ca homepage is generated, because its index.md specifies this template as template.name in its YAML frontmatter (which could also be index.yaml).

  • Guide

    You probably want to start from Markdown ✍️, then Obsidian-style queries and thereon to YAML configuration. See also JavaScript behaviours.

  • Custom CSS styling

    The attributes extension provides the ability to set CSS classes on inline or block level elements of Markdown. You can also specify a “class map” in index.yaml, the default value of which provides some builtin-in styles.

    You should expect the above text to appear styled like a yellow sticky note, because the default index.yaml specifies a “sticky-note” class, which rewrites to a list of Tailwind classes, and that class in turn is (re)used in Markdown notes.

#emanote/yaml/demo