YAML configuration

Note: Emanote documentation is a work-in-progress

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.

For another example, notice how the demo section of this website has a different base site title (see demo.yaml for the underlying configuration).

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). Org Mode has no notion of a "frontmatter", 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.

  • 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.headHtml, 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)
  • 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).

  • 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