Rune is a tool that combines different types of content (like YAML, HTML, Markdown, TSX, SVG, PNG, ZIP, JPG, and JSON) into one easy-to-use JSON format.

This output is designed to securely serve content through a REST API.

Rune is built for everyone on your team — developers, designers, and content creators. It simplifies collaboration by supporting familiar formats like HTML, YAML, Markdown, and TSX, making it easy to manage assets, translations, and views all in one place.

Think of Rune as a master basket weaver, skillfully crafting a basket to hold different kinds of fruits, each familiar to a specific audience:

• HTML files are like apples — crisp, structured, and familiar to frontend developers.
• YAML files are like oranges — layered, segmented, and a favorite of backend developers and system architects.
• JSON translation files are like bananas—rich in meaning, easy to peel apart, and familiar for localization experts.
• Markdown files are like grapes — small, simple, and versatile, perfect for documentation writers. Markdown is not yet implemented. See #22.
• Assets (images, downloadable content, etc.) are like cherries — vibrant, eye-catching, and ready to be included.

Rune carefully weaves a basket — a JSON file — that organizes and holds all these fruits together in a portable and structured way. This basket isn't just static; it can be used as-is or handed to a backend, where more fruits (additional data or assets) can be added later to enrich its contents.

The result is an adaptable basket ready for any use case, whether it's for a simple picnic (a static web content) or a grand feast (a dynamic API-driven application).

• Consolidates YAML (*.yml) and HTML (*.html) files into a single JSON output, embedding any referenced assets as Base64-encoded data URLs.
• Supports reusable components, nested children, and parameterized elements.

• Integrates translations from translations/*.LANG.json files.
• Outputs a flat i18n structure compatible with popular localization libraries.

• Automatically embeds image files and assets as Base64-encoded data URLs.
• Supports SVG and other image formats with MIME type detection.

• Outputs a self-contained JSON file that includes all views, translations, and assets.
• Ideal for static or dynamic web applications.

• Supports custom components and nested structures.
• Allows easy addition of new file types, assets, or features.

To use Rune, ensure you have the following installed:

• Python 3.6 or later
• Required Python libraries:

  pip install -r requirements.txt

You can install Rune using pip:

pip install hyperify-rune

Or clone the repository for development:

git clone https://github.com/hyperifyio/rune.git
cd rune

After installing with pip, you can use the rune command directly:

rune <directory> <output_type>

For example:

rune views json

Structure your project directory as follows:

project/                 # Contains YAML and HTML files
├── translations/        # Contains translation JSON files
│   ├── HelloWorld.en.json
│   └── HelloWorld.fi.json
├── assets/              # May contain images or other assets (or anywhere else on your system)
└── Makefile             # Makefile for build automation. Optional, for easier rebuild.

Example YAML file (views/HelloWorld.yml):

- type: "View"
  name: "HelloWorld"
  body:
  - type: div
    classes:
    - "hello-world-container"
    body:
    - type: h1
      body:
      - "app.title"
  - type: p
    body:
    - "app.content"

Example HTML file (views/HelloWorld.html):

<View name="HelloWorld">
  <div class="hello-world-container">
    <h1>app.title</h1>
    <p>app.content</p>
  </div>
</View>

Create translation files in translations/ (e.g., HelloWorld.en.json):

{
  "app.title": "Hello, World!",
  "app.content": "Welcome to Rune!"
}

Run Rune to merge all YAML, HTML, and translation files into a single JSON:

python3 rune.py views json

The output will look like this:

[
  {
    "type": "View",
    "name": "HelloWorld",
    "body": [
      {
        "type": "div",
        "classes": ["hello-world-container"],
        "body": [
          {"type": "h1", "body": ["app.title"]},
          {"type": "p", "body": ["app.content"]}
        ]
      }
    ]
  },
  {
    "type": "i18n",
    "data": {
      "en": {
        "app.title": "Hello, World!",
        "app.content": "Welcome to Rune!"
      }
    }
  }
]

Define components with parameters and children:

Example (views/UsageCard.html):

<Component name="UsageCard">
  <div class="card">
    <UnfoldableCard title="usageCard.title">
      <Component.Children></Component.Children>
    </UnfoldableCard>
  </div>
</Component>

Embed files directly into the JSON output:

Example YAML asset (views/assets.yml):

- type: "Asset"
  name: "logo"
  body: "data:image/png;base64,xxxxx"

Automatically embed images referenced in properties like Image, src, or custom attributes.

Example HTML (views/Example.html):

<Foo heroImage="../assets/logo.png"></Foo>

• --assets-dir PATH: Save extracted attachments to PATH. When unset, attachments remain embedded as data-URLs (default).
• --assets-prefix PREFIX: Rewrite asset URLs in the output to start with PREFIX (useful when assets are served from a CDN or static host).

CLI flags override configuration values when both are provided.

Examples:

rune --assets-dir out/assets views json

rune --assets-prefix /static/assets views json

python3 rune.py <directory> <output_type>

• <directory>: The project directory containing *.yml, *.html, and translations/.
• <output_type>: Either json or yml.

Rune is licensed under [./LICENSE.md](the Functional Source License, Version 1.1, MIT Future License).

For questions, feedback, or commercial inquiries, contact us at info@hyperify.io.