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.

Using in HTML templates

You can reference the YAML frontmatter config from HTML Templates. See here for details.

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

    A predefined snippet also exists for another syntax highlighter called Prism. To use it add the following to page.headHtml of YAML configuration or Markdown frontmatter.

    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 or Markdown frontmatter. 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 page.bodyHtml of YAML configuration or Markdown frontmatter.

  • Math

    To enable it, add the following to page.headHtml of YAML configuration or Markdown frontmatter.

  • 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 some predefined behaviours, like syntax highlighting or rendering of mathematical formulas. They can be accessed by including appropriate snippets in page.headHtml or page.bodyHtml of YAML configuration files (if adding to all or multiple routes) or Markdown frontmatter (if adding to a single route). The source code for the snippets can be found in the default index.yaml under the js: YAML map.

  • 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.

  • Full-text search

    This can be changed by adding the following to `index.yaml`:

  • 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.

  • ATOM feed
    feed.siteUrl: the site url, default to global setting from the index.yaml.

    An atom feed can be generated for a given note query by adding the following to the note metadata:

    [!note] feed.siteUrl You must set feed.siteUrl (see below) in the index.yaml for the feed to be generated.

#emanote/yaml/demo