{"id":27696570,"url":"https://github.com/levinunnink/merge.js","last_synced_at":"2025-04-25T15:11:34.386Z","repository":{"id":39716134,"uuid":"299367249","full_name":"levinunnink/merge.js","owner":"levinunnink","description":"A simple, highly portable templating engine. You can load templates in your browser or export the output as static HTML. Runnable in the browser or CLI.","archived":false,"fork":false,"pushed_at":"2023-10-03T09:05:24.000Z","size":3340,"stargazers_count":34,"open_issues_count":7,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-20T19:37:15.427Z","etag":null,"topics":["html","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/levinunnink.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-28T16:25:52.000Z","updated_at":"2024-08-23T02:51:36.000Z","dependencies_parsed_at":"2023-02-08T02:47:51.515Z","dependency_job_id":null,"html_url":"https://github.com/levinunnink/merge.js","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levinunnink%2Fmerge.js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levinunnink%2Fmerge.js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levinunnink%2Fmerge.js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levinunnink%2Fmerge.js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/levinunnink","download_url":"https://codeload.github.com/levinunnink/merge.js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250628972,"owners_count":21461720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["html","javascript"],"created_at":"2025-04-25T15:11:33.785Z","updated_at":"2025-04-25T15:11:34.374Z","avatar_url":"https://github.com/levinunnink.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Merge \u003cimg align=\"right\" width=\"200\" src=\"https://files.nunn.ink/AuGqPy.jpg\" /\u003e\n\n[![Actions Status](https://github.com/levinunnink/merge.js/workflows/Tests/badge.svg)](https://github.com/levinunnink/merge.js/actions) [![npm version](https://badge.fury.io/js/%40smmall%2Fmerge.svg)](https://badge.fury.io/js/%40smmall%2Fmerge)\n\nMerge is a HTML templating engine for HTML developers that's portable enough to run in the browser or on the command line. It's primary function is to merge JSON data into HTML files using standards compliant HTML and output it to the browser or file system. It gives the same output if you're running it in your browser or publishing it as static html.\n\nA basic merge template looks like:\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eHello, \u003cspan data-merge-content=\"name\"\u003e\u003c/span\u003e\u003c/h1\u003e\n    \u003cscript\u003e\n      merge.loadState({ name: 'World' });\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nwhich the Merge engine will convert to\n\n```html\n\u003chtml\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eHello, \u003cspan\u003eWorld\u003c/span\u003e\u003c/h1\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Table of Contents\n\n- [Principles](#principles)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Starting a Merge Server](#starting-a-merge-server)\n  - [Building Static HTML](#building-static-html)\n- [Merge HTML Guide](#merge-html-guide)\n  - [Loading data into the engine](#loading-data-into-the-engine)\n  - [Loading from a URL](#loading-from-a-url)\n  - [Loading from a JSON object](#loading-from-a-json-object)\n  - [Merge Attributes](#merge-attributes)\n  - [Includes: data-merge-include](#includes-data-merge-include)\n  - [Markdown: data-merge-include-markdown](#markdown-data-merge-include-markdown)\n  - [Variables: data-merge-content](#variables-data-merge-content)\n  - [Conditionals: data-merge-if](#conditionals-data-merge-if)\n  - [Loops: data-merge-repeat](#loops-data-merge-repeat)\n  \n\n### Principles\n\n- ☝️ **HTML + CSS first.** Merge is here to empower you to build your site in HTML without having to resort to a static site generator, or switching to Javascript.\n- ⛵️ **Portability.** Merge is a template engine that is portable. You can embed it in your apps or build process with minimal effort. \n- 🛀 **Clean static output.** Merge cleans up after itself. After Merge is done building your HTML, it removes all signs that it was ever there.\n- 🔥 **Dynamic development.** Because Merge is written in Javascript, you can run it right in your browser without any hassle. Our server will watch your HTML for changes and automatically refresh as you work.\n- 👌 **Zero configuration.** Running Merge should just work. We want to help you write HTML and CSS, not config files.\n\n### Installation\n\n**NPM:**\n\nOpen your terminal and run:\n\n```shell\n$ npm install -g @smmall/merge\n```\n\n**CDN:**\n\nYou can put this reference in the body of your HTML page.\n\n```html\n\u003cscript src=\"https://unpkg.com/@smmall/merge/dist/Merge.min.js\"\u003e\u003c/script\u003e\n```\n\n**Note:** We recommend that you only use the CDN version for development purposes. For production deployment, use the NPM version.\n\n## Usage\n\n```shell\nUsage: merge [options] [command]\n\nOptions:\n  -V, --version                        output the version number\n  -h, --help                           display help for command\n\nCommands:\n  serve \u003cdirectory\u003e                    Serves a local directory using the merge runtime\n  build \u003cdirectory\u003e [destinationPath]  Compiles the local HTML and outputs it to the destination path\n  help [command]                       display help for command\n```\n\nOnce you've installed the Merge engine, you can start a server or build your HTML for production.\n\n### Starting a Merge server\n\nThe Merge server will automatically run your HTML inside of the Merge engine and reload in the browser as you make changes. \n\n```shell\n$ merge serve ./path-to/my-folder\n```\n\nTo stop the server just run `CMD+.` on Mac or `CTRL+Z` on Windows.\n\n_⚠️ You should only use the Merge server for local development. It is not suitable for production use._\n\n### Building static HTML\n\nTo build your HTML with Merge, you'll also need to specify a destination folder where you want your built HTML to go.\n\n```shell\n$ merge build ./path-to/my-folder ./path-to/my-destination\n```\n\n# Merge HTML Guide\n\nMerge uses standards-compliant HTML to communicate with the engine and explain how to merge the JSON data with the HTML tags. The goal of this is to allow you to do as much as possible with simple HTML development, instead of forcing you to learn new workflows and write HTML using Javascript.\n\n## Loading data into the engine state\n\nTo merge your HTML with the data, the Merge engine needs a JSON object that describes the data. This is the one place where you need to use a little Javascript. Any data you load must be in a valid JSON format. Merge will render your page once all `loadState` functions are complete.\n\n### Loading from a URL\n\nYou can load your JSON data from a URL.\n\n```html\n\u003cscript data-type=\"merge-script\"\u003e\n  document.addEventListener('DOMContentLoaded', function() {\n    merge.loadState('/site.json');\n  }, false);\n\u003c/script\u003e\n```\n\nNote: If you're running Merge in the browser, the URL you load data from must implement [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) or an error will be thrown. If you are loading data from the same domain, then you don't need to worry about CORS.\n\n### Loading from a JSON object\n\nYou can load data directly into the state using a JSON object:\n\n```html\n\u003ch1\u003eHi, \u003cspan data-merge-content=\"name\"\u003e\u003c/span\u003e\u003c/h1\u003e\n\u003cscript data-type=\"merge-script\"\u003e\n  document.addEventListener('DOMContentLoaded', function() {\n    merge.loadState({\n      name: 'Joe',\n    });\n  }, false);\n\u003c/script\u003e\n```\n\n## Merge Attributes\n\nMerge reads `data` attributes on the elements to understand how to merge the state data with the HTML.\n\n### Includes: data-merge-include\n\nYou can include HTML files with Merge by adding the `data-merge-include` attribute to an element:\n\n```html\n\u003cdiv data-merge-include=\"footer.html\"\u003e\u003c/div\u003e\n```\n\n**Note:** By default the `data-merge-include` attribute will replace the contents of the html element with the included html. If you want to append the contents to the html, use the `data-merge-include-type=\"append\"` attribute.\n\n```html\n\u003chead data-merge-include=\"meta.html\"\u003e\n  \u003ctitle\u003eMy page title\u003c/title\u003e\n  \u003c!-- The contents of meta.html will be added here --\u003e\n\u003c/head\u003e\n```\n\n### Markdown: data-merge-include-markdown\n\nYou can include and parse markdown files with Merge by adding the `data-merge-include-markdown` attribute to an element:\n\n```html\n\u003cdiv data-merge-include-markdown=\"article.md\"\u003e\u003c/div\u003e\n```\n\n**Note:** If you're not running the local server or the complier, you will need to provide a markdown parsing function by setting the `parseMarkdown` property on the merge object. We recommend [marked](https://github.com/markedjs/marked) but you can use any function you want. Your function just needs to accept a markdown string and return the parsed html.\n\n```javascript\nconst marked = require('marked');\nmerge.parseMarkdown = marked;\n```\n\n### Variables: data-merge-content\n\nYou can set the content of an HTML element using the `data-merge-content` attribute and a valid context:\n\n```html\n\u003ch1\u003eHi \u003cspan data-merge-content=\"name.first\"\u003e\u003c/span\u003e\u003c/h1\u003e\n\u003cscript data-type=\"merge-script\"\u003e\n  document.addEventListener('DOMContentLoaded', function() {\n    merge.loadState({\n      name: {\n        first: 'Jane',\n        last: 'Doe',\n      }\n    });\n  }, false);\n\u003c/script\u003e\n```\n\n### Conditionals: data-merge-if\n\nYou can show or hide HTML elements using the `data-merge-if` and `data-merge-equals` attributes:\n\n```html\n\u003cdiv data-merge-if=\"day\" data-merge-equals=\"friday\"\u003eTGIF!\u003c/div\u003e\n\u003cscript data-type=\"merge-script\"\u003e\n  document.addEventListener('DOMContentLoaded', function() {\n    merge.loadState({ day: 'friday' });\n  }, false);\n\u003c/script\u003e\n```\n\nIf you only want to check for the existence of a property, you can leave off the `data-merge-equals` attribute and Merge will show the element if the property exists in the state.\n\n```html\n\u003cdiv data-merge-if=\"happy\"\u003eYAY! I'm glad you're happy.\u003c/div\u003e\n\u003cdiv data-merge-if=\"sad\"\u003eAww! I'm sorry you're sad.\u003c/div\u003e\n\u003cscript data-type=\"merge-script\"\u003e\n  document.addEventListener('DOMContentLoaded', function() {\n    merge.loadState({ happy: true });\n  }, false);\n\u003c/script\u003e\n```\n\n### Loops: data-merge-repeat\n\nYou can loop over elements in an Array using the `data-merge-repeat` and Javascript template substitutions.\n\n\n```html\n\u003cul class=\"links\" data-merge-repeat=\"items\"\u003e\n  \u003cli\u003e\n    \u003ca href=\"${link}\"\u003e${label}\u003c/a\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n\u003cscript data-type=\"merge-script\"\u003e\ndocument.addEventListener('DOMContentLoaded', function() {\n  merge.loadState({\n    items: [{\n        link: \"https://nunn.ink\",\n        label: \"Personal Site\"\n      },\n      {\n        link: \"https://twitter.com/LeviNunnink\",\n        label: \"Twitter\"\n      },\n      {\n        link: \"https://github.com/LeviNunnink\",\n        label: \"Github\"\n      }\n    ],\n  });\n}, false);\n\u003c/script\u003e\n```\n\n## Contributing \n\nIf you have ideas for improvements, feel free to open a PR or an issue and I'll do my best to review it promptly.\n\n## Author\n\n- Levi Nunnink - [@levinunnink](https://twitter.com/levinunnink)\n\n## License\n\nPublished under the MIT License.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevinunnink%2Fmerge.js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevinunnink%2Fmerge.js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevinunnink%2Fmerge.js/lists"}