{"id":42126259,"url":"https://github.com/hyperifyio/rune","last_synced_at":"2026-01-26T15:09:01.631Z","repository":{"id":248238975,"uuid":"828153125","full_name":"hyperifyio/rune","owner":"hyperifyio","description":"Rune: A content preprocessor that combines YAML, HTML, Markdown, TSX, and more into a secure, API-ready JSON format. Built for seamless collaboration across teams.","archived":false,"fork":false,"pushed_at":"2025-09-06T09:46:19.000Z","size":26475,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-06T11:36:45.516Z","etag":null,"topics":["api-ready","asset-management","collaborative-tool","content-management","content-preprocessor","designer-friendly","developer-tools","html","json-preprocessor","markdown","multi-format-support","rest-api","svg","translation-support","tsx","yaml"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperifyio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-07-13T09:22:42.000Z","updated_at":"2025-09-06T09:46:22.000Z","dependencies_parsed_at":"2024-07-13T10:53:53.330Z","dependency_job_id":"a145873f-f7f3-4638-a4af-b10e47308628","html_url":"https://github.com/hyperifyio/rune","commit_stats":null,"previous_names":["hyperifyio/rune"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hyperifyio/rune","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperifyio%2Frune","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperifyio%2Frune/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperifyio%2Frune/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperifyio%2Frune/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperifyio","download_url":"https://codeload.github.com/hyperifyio/rune/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperifyio%2Frune/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28781308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-ready","asset-management","collaborative-tool","content-management","content-preprocessor","designer-friendly","developer-tools","html","json-preprocessor","markdown","multi-format-support","rest-api","svg","translation-support","tsx","yaml"],"created_at":"2026-01-26T15:09:01.572Z","updated_at":"2026-01-26T15:09:01.624Z","avatar_url":"https://github.com/hyperifyio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rune\n\n**Rune** is a tool that combines different types of content (like YAML, HTML,\n[Markdown](https://github.com/hyperifyio/rune/issues/22), \n[TSX](https://github.com/hyperifyio/rune/issues/26), SVG, PNG, ZIP, JPG, and \nJSON) into one easy-to-use JSON format.\n\nThis output is designed to securely serve content through a REST API.\n\nRune is built for everyone on your team — developers, designers, and content \ncreators. It simplifies collaboration by supporting familiar formats like HTML, \nYAML, Markdown, and TSX, making it easy to manage assets, translations, and \nviews all in one place.\n\n## Metaphor: Rune and the Basket of Fruits\n\nThink of Rune as a master basket weaver, skillfully crafting a basket to hold \ndifferent kinds of fruits, each familiar to a specific audience:\n\n- **HTML files** are like apples — crisp, structured, and familiar to frontend \n  developers.\n- **YAML files** are like oranges — layered, segmented, and a favorite of \n  backend developers and system architects.\n- **JSON translation files** are like bananas—rich in meaning, easy to peel \n  apart, and familiar for localization experts.\n- **Markdown files** are like grapes — small, simple, and versatile, perfect for \n  documentation writers. *Markdown is not yet implemented.* See\n  [#22](https://github.com/hyperifyio/rune/issues/22).\n- **Assets (images, downloadable content, etc.)** are like cherries — vibrant, \n  eye-catching, and ready to be included.\n\nRune carefully weaves a basket — a JSON file — that organizes and holds all\nthese fruits together in a portable and structured way. This basket isn't just \nstatic; it can be used as-is or handed to a backend, where more fruits \n(additional data or assets) can be added later to enrich its contents.\n\nThe result is an adaptable basket ready for any use case, whether it's for a \nsimple picnic (a static web content) or a grand feast (a dynamic API-driven \napplication).\n\n## Key Features\n\n### 1. **Dynamic Content Processing**\n\n- Consolidates YAML (`*.yml`) and HTML (`*.html`) files into a single JSON \n  output, embedding any referenced assets as Base64-encoded data URLs.\n- Supports reusable components, nested children, and parameterized elements.\n\n### 2. **Multilingual Support**\n\n- Integrates translations from `translations/*.LANG.json` files.\n- Outputs a flat `i18n` structure compatible with popular localization \n  libraries.\n\n### 3. **Embedded Assets**\n\n- Automatically embeds image files and assets as Base64-encoded data URLs.\n- Supports SVG and other image formats with MIME type detection.\n\n### 4. **Portability**\n\n- Outputs a self-contained JSON file that includes all views, translations, and \n  assets.\n- Ideal for static or dynamic web applications.\n\n### 5. **Extensibility**\n\n- Supports custom components and nested structures.\n- Allows easy addition of new file types, assets, or features.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\nTo use Rune, ensure you have the following installed:\n\n- Python 3.6 or later\n- Required Python libraries:\n  ```bash\n  pip install -r requirements.txt\n  ```\n\n---\n\n### Installation\n\nYou can install Rune using pip:\n\n```bash\npip install hyperify-rune\n```\n\nOr clone the repository for development:\n\n```bash\ngit clone https://github.com/hyperifyio/rune.git\ncd rune\n```\n\n---\n\n### Usage\n\n#### **1. Using the Command Line Tool**\n\nAfter installing with pip, you can use the `rune` command directly:\n\n```bash\nrune \u003cdirectory\u003e \u003coutput_type\u003e\n```\n\nFor example:\n```bash\nrune views json\n```\n\n#### **2. Prepare Your Project Directory**\n\nStructure your project directory as follows:\n\n```\nproject/                 # Contains YAML and HTML files\n├── translations/        # Contains translation JSON files\n│   ├── HelloWorld.en.json\n│   └── HelloWorld.fi.json\n├── assets/              # May contain images or other assets (or anywhere else on your system)\n└── Makefile             # Makefile for build automation. Optional, for easier rebuild.\n```\n\n#### **3. Add YAML or HTML Views**\n\nExample YAML file (`views/HelloWorld.yml`):\n\n```yaml\n- type: \"View\"\n  name: \"HelloWorld\"\n  body:\n  - type: div\n    classes:\n    - \"hello-world-container\"\n    body:\n    - type: h1\n      body:\n      - \"app.title\"\n  - type: p\n    body:\n    - \"app.content\"\n```\n\nExample HTML file (`views/HelloWorld.html`):\n\n```html\n\u003cView name=\"HelloWorld\"\u003e\n  \u003cdiv class=\"hello-world-container\"\u003e\n    \u003ch1\u003eapp.title\u003c/h1\u003e\n    \u003cp\u003eapp.content\u003c/p\u003e\n  \u003c/div\u003e\n\u003c/View\u003e\n```\n\n#### **4. Add Translations**\n\nCreate translation files in `translations/` (e.g., `HelloWorld.en.json`):\n\n```json\n{\n  \"app.title\": \"Hello, World!\",\n  \"app.content\": \"Welcome to Rune!\"\n}\n```\n\n#### **5. Build the Project**\n\nRun Rune to merge all YAML, HTML, and translation files into a single JSON:\n\n```bash\npython3 rune.py views json\n```\n\nThe output will look like this:\n\n```json\n[\n  {\n    \"type\": \"View\",\n    \"name\": \"HelloWorld\",\n    \"body\": [\n      {\n        \"type\": \"div\",\n        \"classes\": [\"hello-world-container\"],\n        \"body\": [\n          {\"type\": \"h1\", \"body\": [\"app.title\"]},\n          {\"type\": \"p\", \"body\": [\"app.content\"]}\n        ]\n      }\n    ]\n  },\n  {\n    \"type\": \"i18n\",\n    \"data\": {\n      \"en\": {\n        \"app.title\": \"Hello, World!\",\n        \"app.content\": \"Welcome to Rune!\"\n      }\n    }\n  }\n]\n```\n\n---\n\n## Advanced Features\n\n### **Reusable Components**\n\nDefine components with parameters and children:\n\nExample (`views/UsageCard.html`):\n```html\n\u003cComponent name=\"UsageCard\"\u003e\n  \u003cdiv class=\"card\"\u003e\n    \u003cUnfoldableCard title=\"usageCard.title\"\u003e\n      \u003cComponent.Children\u003e\u003c/Component.Children\u003e\n    \u003c/UnfoldableCard\u003e\n  \u003c/div\u003e\n\u003c/Component\u003e\n```\n\n### **Embedded Assets**\n\nEmbed files directly into the JSON output:\n\nExample YAML asset (`views/assets.yml`):\n```yaml\n- type: \"Asset\"\n  name: \"logo\"\n  body: \"data:image/png;base64,xxxxx\"\n```\n\n### **Image Handling**\n\nAutomatically embed images referenced in properties like `Image`, `src`, or custom attributes.\n\nExample HTML (`views/Example.html`):\n```html\n\u003cFoo heroImage=\"../assets/logo.png\"\u003e\u003c/Foo\u003e\n```\n\n---\n\n## CLI Options\n\n### Optional flags\n\n- --assets-dir PATH: Save extracted attachments to PATH. When unset, attachments remain embedded as data-URLs (default).\n- --assets-prefix PREFIX: Rewrite asset URLs in the output to start with PREFIX (useful when assets are served from a CDN or static host).\n\nCLI flags override configuration values when both are provided.\n\nExamples:\n\n```bash\nrune --assets-dir out/assets views json\n```\n\n```bash\nrune --assets-prefix /static/assets views json\n```\n\n\n```bash\npython3 rune.py \u003cdirectory\u003e \u003coutput_type\u003e\n```\n\n- `\u003cdirectory\u003e`: The project directory containing `*.yml`, `*.html`, and `translations/`.\n- `\u003coutput_type\u003e`: Either `json` or `yml`.\n\n---\n\n## License\n\n**Rune** is licensed under [./LICENSE.md](the Functional Source License, Version 1.1, MIT Future License).\n\n---\n\n## Contact\n\nFor questions, feedback, or commercial inquiries, contact us at [info@hyperify.io](mailto:info@hyperify.io).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperifyio%2Frune","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperifyio%2Frune","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperifyio%2Frune/lists"}