REVELation Architecture Reference

Table of Contents

• System Overview
• Reveal.js Runtime Integration
• Default Plugin Stack
• Inter-Presentation Link Resolution
• Builder Plugin Hooks
• Offline Export Plugin Hooks
• Core CLI Workflows

System Overview

REVELation is a Reveal.js-based markdown presentation framework with:

• YAML-driven metadata and authoring extensions
• Preprocessing for macros, media aliases, and custom markdown syntax
• Runtime pages for presentation, handout, media library, and listing views

Primary entry points in this module include revelation/presentation.html, revelation/handout.html, revelation/presentations.html, and revelation/media-library.html.

Reveal.js Runtime Integration

You can set Reveal.js options in front matter config:.

config:
  transition: fade
  controls: false
  slideNumber: c
  hash: true
  progress: true
  autoAnimate: true

All standard Reveal.js data attributes and HTML patterns are supported in processed markdown output.

Default Plugin Stack

The runtime enables Reveal.js plugins including:

• Markdown
• Notes
• Zoom
• Search
• Remote (when network mode is enabled)

Inter-Presentation Link Resolution

Author-facing markdown uses plain relative .md links (for example [Next](something.md)), not implementation-specific query URLs.

Planned resolution model:

• Treat links ending in .md (optionally with #anchor) as internal presentation navigation.
• Preserve markdown portability by mapping these links at runtime/generation time.
• Reject parent-directory traversal targets (for example ../other.md) for safety.
• Support flattened generated docs where linked .md targets live in the same presentation directory.

Current runtime path base behavior:

• Markdown file loading (?p=...) resolves from the presentation root directory (the folder containing index.html), even when p points to nested paths like nest1/nest2/deep.md.
• Markdown links inside slides are interpreted relative to that same presentation root for navigation (?p=...), not relative to the current markdown file's own folder.
• Media alias resolution (media: and _media fetch paths), theme stylesheet paths, and related runtime asset references also use the presentation root model.

Builder Plugin Hooks

Plugins can contribute builder menu content via browser-side hooks:

• getContentCreators(context) (legacy)
• getBuilderTemplates(context) (recommended)

Template items can provide:

• label or title
• template / markdown / content
• slides / stacks
• onSelect(ctx) or build(ctx)

Context can include:

• slug, mdFile, dir, origin, insertAt
• insertContent(payload)

If onSelect/build calls insertContent(...), insertion is treated as complete.

Offline Export Plugin Hooks

Plugins can provide offline.js in their folder with:

• build(context) (optional)
• export(context) (optional)

export(context) may return:

• pluginListEntry
• headTags
• bodyTags
• copy entries with { from, to }

Example:

module.exports = {
  async export(ctx) {
    return {
      pluginListEntry: {
        baseURL: './_resources/plugins/example',
        clientHookJS: 'client.js',
        priority: 100,
        config: {}
      },
      copy: [
        { from: 'client.js', to: 'plugins/example/client.js' },
        { from: 'dist', to: 'plugins/example/dist' }
      ]
    };
  }
};

Core CLI Workflows

Common framework scripts:

For markdown authoring details, use revelation/doc/AUTHORING_REFERENCE.md and revelation/doc/METADATA_REFERENCE.md.

Documentation Hub

Back to Documentation Hub