Slide Templating and Metadata

[spkane]

I am looking for a way to use the frontmatter (with some custom fields) to provide simple strings that would be templated into the rendered slides.

It would be useful to be able to use some of the existing frontmatter fields like title and author, plus anything else that is added into the frontmatter and be able to use them to template sections through out the slide deck.

e.g.

---
marp: true
title: My Presentation
subtitle: Getting Started in Life
author: Sean
---
<!-- _class: lead -->
<!-- size: 16:9 -->

# {{ title }}
## {{ subtitle }}

##### Presented by {{ author }}
---

Is there already a reasonably easy way to do this? I'd prefer not to introduce a new tool at the moment, but I am open to suggestions if that is the only option.

Thanks!

Sean

[yhatt]

It could be achieved with making a plugin for Marp(it) with following logic:

1. Register the estimated custom keys for placeholder as the custom global directives
2. Add the inline rule of markdown-it to parse {{ xxx }} and replace with the custom placeholder token
3. Append the core rule after the rule for parsing Marpit's global directives (marpit_directives_global_parse core rule), to replace the content of custom placeholder tokens with the value of global directives

Tip

Marpit will recognize only pre-registered directives while parsing Markdown. So it might be better to use the nested object definition within the pre-registered custom global directive if you want to allow the custom placeholder name in the Markdown document.

---
meta:
  foo: xxx
  bar: xxx
---

marpit.customDirectives.global.meta = (value) =>
  typeof value === 'object' ? { meta: value } : {}

[spkane]

Thank you @yhatt. That is helpful.

Although I do some development, I am very new to Javascript and Marp's codebase, so I am very slowly make sense of it all.

At the moment, I have a very simple use case started just using the engine file (without a plugin) like so:

const { Marp } = require('@marp-team/marp-core')

const marpOpts = {
  html: true,
}

function getFullTimestamp() {
  const pad = (n, s = 2) => (`${new Array(s).fill(0)}${n}`).slice(-s);
  const d = new Date();

  return `${pad(d.getFullYear(), 4)}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
}

module.exports = marpOpts => {
  const md = new Marp(marpOpts)

  md.customDirectives.global.author = (value) => {
    return { author: "Me" }
  }

  const proxy = (tokens, idx, options, env, self) => md.markdown.renderer.renderToken(tokens, idx, options);
  const defaultTextRenderer = md.markdown.renderer.rules.text || proxy;

  const timestamp = getFullTimestamp()

  md.markdown.renderer.rules.text = (tokens, idx, options, env, self) => {
    let text = tokens[idx].content;

    let step2 = text.replace(/{{{AUTHOR}}}/g, "TEST"); // How to get the value of the globalDirective?

    tokens[idx].content = step2.replace(/{{{TIMESTAMP}}}/g, timestamp);
    return defaultTextRenderer(tokens, idx, options, env, self)
  };

  return md
}

I am struggling with getting the string value (Me) from the custom globalDirective author, so that I can replace the text `{{{AUTHOR}}}`` with that value.

Any help/pointers would be greatly appreciated.

Thank you!

Sean

[yhatt]

The returned key-value will assign to marpitDirectives property in meta object of predetermined markdown-it token(s) by the kind of directive. It would be useful for using assigned value in markdown-it plugin.

— https://marpit.marp.app/directives

The value of stored global directives have been defined in the meta object of opening tokens for each slide (marpit_slide_open token), and the same defined value is stored in every slide tokens.

For reading directives, scan the tokens in the core rule and find out the value from meta.marpitDirectives key in the token. Note that this object has mixed directive values from global directives and local directives.

Example

The placeholderPlugin function will parse the placeholder text such as {{ foo }} as placeholder inline token, and after parsing directives, replace the content of placeholders to the text that is defined in the meta custom global directive. Making custom markdown-it token type is a neat way that is adopted in a lot of markdown-it plugins.

// marp.config.mjs
import { defineConfig } from '@marp-team/marp-cli'

const placeholderPlugin = (md) => {
  // Add `meta` global directive to Marpit, for storing meta values for placeholders.
  md.marpit.customDirectives.global.meta = (value) => {
    if (typeof value === 'object') {
      return { meta: value }
    } else {
      return {}
    }
  }

  // Add `placeholder` inline rule to parse placeholders like {{ this }}.
  md.inline.ruler.before('escape', 'placeholder', (state, silent) => {
    const { src, pos } = state
    if (src.substr(pos, 2) !== '{{') return false

    // Find end position
    let endPos = pos + 2
    let found = true

    while (endPos < src.length) {
      if (src.substr(endPos, 2) === '}}') {
        found = true
        endPos += 2
        break
      }
      endPos += 1
    }

    if (!found) return false

    // Add placeholder token
    if (!silent) {
      const token = state.push('placeholder', '', 0)
      token.content = src.slice(pos, endPos)
      token.info = src.slice(pos + 2, endPos - 2).trim()
    }

    state.pos = endPos
    return true
  })

  md.core.ruler.after(
    'marpit_directives_apply',
    'placeholder_apply',
    (state) => {
      if (state.inlineMode) return

      let currentMeta = {}

      for (const token of state.tokens) {
        if (
          typeof token.meta?.marpitDirectives === 'object' &&
          typeof token.meta.marpitDirectives.meta === 'object'
        ) {
          // Assign metadata if found
          currentMeta = token.meta.marpitDirectives.meta
        }

        if (token.type === 'inline') {
          // Replace content for each placeholder token with the metadata value that is defined in nearest
          for (const inlineToken of token.children) {
            if (inlineToken.type === 'placeholder') {
              if (typeof currentMeta[inlineToken.info] === 'string') {
                inlineToken.content = currentMeta[inlineToken.info]
              }
            }
          }
        }
      }
    }
  )

  // Render placeholder token as escaped HTML
  md.renderer.rules.placeholder = (tokens, idx) =>
    md.utils.escapeHtml(tokens[idx].content)
}

export default defineConfig({
  engine: ({ marp }) => marp.use(placeholderPlugin),
})

---
meta:
  foo: Hello
  bar: World
---

# {{ foo }}, {{ bar }}!