YAML configuration

Configure your site metadata, rendering configuration and such using YAML configuration. Create a foo.yaml alongside foo.md (see Folder notes) 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.

Special properties

  • page.image: The image to use for the page. This is used for the Open Graph Protocol (OGP) meta tag og:image meta tag. If not specified, the first image in the page is used. Relative URLs are automatically rewritten to absolute URLs if page.siteUrl is non-empty.


Links to this page
  • Uplink tree

    To enable the uptree, add the following to your YAML configuration:

  • Table of contents
  • 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

    The sidebar will use a page’s title by default, but you can override the sidebar item text by setting the short-title frontmatter property.

  • Org Mode ✍️
    While #+TITLE is recognized, other metadata are not recognized (yet). Therefore you must store file-associated metadata in a separate YAML file.
  • Open Graph Protocol (OGP)
    The first image* in the note, if any; otherwise, use the image YAML metadata
    The site name from page.siteTitle

    Twitter Card style can be set using page.twitter.card YAML metadata. It it set to summary_large_image by default.

  • 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’s builtin HTML template layout can be configured to toggle UX features on or off. The default configuration includes Sidebar, Table of contents and Breadcrumbs but hides the Uplink tree. To mimic the layout used by Neuron, turn off sidebar and breadcrumbs while enabling the uptree. Add this to your YAML configuration:

  • 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 a default layout that includes a Sidebar, but can be customized to mimic Neuron-like layout. You may 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`:

  • Folgezettel links

    This behavior can be configured. To turn it off on a per-folder basis, set the corresponding flag in your configuration to false as shown here:

    [!tip] Put this configuration in foo.md if you want to disable folder folgezettel for just that folder note foo/. Put it in foo.yaml if you want to disable it for foo/ and all subfolders under it recursively. Put it in top-level index.yaml to disable it for all folders. See YAML configuration for more details.

  • Folder notes

    For every folder foo/ in your notebook, if a foo.md exists alongside it, it is consider a “folder note” that is associated with the folder. Likewise, an associated foo.yaml servers as the YAML configuration for the entire folder and its contents recursively.

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

  • Breadcrumbs

    On mobile view, breadcrumbs are displayed at the top. The path of the crumbs is determined from the filesystem path of the associated source file. Breadcrumbs can be disabled in YAML configuration; see Neuron-like layout for an example.

  • ATOM feed

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

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