https://github.com/levinunnink/merge.js
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.
https://github.com/levinunnink/merge.js
html javascript
Last synced: about 1 year ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/levinunnink/merge.js
- Owner: levinunnink
- License: mit
- Created: 2020-09-28T16:25:52.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-03T09:05:24.000Z (almost 3 years ago)
- Last Synced: 2025-03-20T19:37:15.427Z (over 1 year ago)
- Topics: html, javascript
- Language: JavaScript
- Homepage:
- Size: 3.19 MB
- Stars: 34
- Watchers: 5
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Merge 
[](https://github.com/levinunnink/merge.js/actions) [](https://badge.fury.io/js/%40smmall%2Fmerge)
Merge 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.
A basic merge template looks like:
```html
Hello,
merge.loadState({ name: 'World' });
```
which the Merge engine will convert to
```html
Hello, World
```
## Table of Contents
- [Principles](#principles)
- [Installation](#installation)
- [Usage](#usage)
- [Starting a Merge Server](#starting-a-merge-server)
- [Building Static HTML](#building-static-html)
- [Merge HTML Guide](#merge-html-guide)
- [Loading data into the engine](#loading-data-into-the-engine)
- [Loading from a URL](#loading-from-a-url)
- [Loading from a JSON object](#loading-from-a-json-object)
- [Merge Attributes](#merge-attributes)
- [Includes: data-merge-include](#includes-data-merge-include)
- [Markdown: data-merge-include-markdown](#markdown-data-merge-include-markdown)
- [Variables: data-merge-content](#variables-data-merge-content)
- [Conditionals: data-merge-if](#conditionals-data-merge-if)
- [Loops: data-merge-repeat](#loops-data-merge-repeat)
### Principles
- ☝️ **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.
- ⛵️ **Portability.** Merge is a template engine that is portable. You can embed it in your apps or build process with minimal effort.
- 🛀 **Clean static output.** Merge cleans up after itself. After Merge is done building your HTML, it removes all signs that it was ever there.
- 🔥 **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.
- 👌 **Zero configuration.** Running Merge should just work. We want to help you write HTML and CSS, not config files.
### Installation
**NPM:**
Open your terminal and run:
```shell
$ npm install -g @smmall/merge
```
**CDN:**
You can put this reference in the body of your HTML page.
```html
```
**Note:** We recommend that you only use the CDN version for development purposes. For production deployment, use the NPM version.
## Usage
```shell
Usage: merge [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
serve Serves a local directory using the merge runtime
build [destinationPath] Compiles the local HTML and outputs it to the destination path
help [command] display help for command
```
Once you've installed the Merge engine, you can start a server or build your HTML for production.
### Starting a Merge server
The Merge server will automatically run your HTML inside of the Merge engine and reload in the browser as you make changes.
```shell
$ merge serve ./path-to/my-folder
```
To stop the server just run `CMD+.` on Mac or `CTRL+Z` on Windows.
_⚠️ You should only use the Merge server for local development. It is not suitable for production use._
### Building static HTML
To build your HTML with Merge, you'll also need to specify a destination folder where you want your built HTML to go.
```shell
$ merge build ./path-to/my-folder ./path-to/my-destination
```
# Merge HTML Guide
Merge 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.
## Loading data into the engine state
To 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.
### Loading from a URL
You can load your JSON data from a URL.
```html
document.addEventListener('DOMContentLoaded', function() {
merge.loadState('/site.json');
}, false);
```
Note: 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.
### Loading from a JSON object
You can load data directly into the state using a JSON object:
```html
Hi,
document.addEventListener('DOMContentLoaded', function() {
merge.loadState({
name: 'Joe',
});
}, false);
```
## Merge Attributes
Merge reads `data` attributes on the elements to understand how to merge the state data with the HTML.
### Includes: data-merge-include
You can include HTML files with Merge by adding the `data-merge-include` attribute to an element:
```html
```
**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.
```html
My page title
```
### Markdown: data-merge-include-markdown
You can include and parse markdown files with Merge by adding the `data-merge-include-markdown` attribute to an element:
```html
```
**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.
```javascript
const marked = require('marked');
merge.parseMarkdown = marked;
```
### Variables: data-merge-content
You can set the content of an HTML element using the `data-merge-content` attribute and a valid context:
```html
Hi
document.addEventListener('DOMContentLoaded', function() {
merge.loadState({
name: {
first: 'Jane',
last: 'Doe',
}
});
}, false);
```
### Conditionals: data-merge-if
You can show or hide HTML elements using the `data-merge-if` and `data-merge-equals` attributes:
```html
TGIF!
document.addEventListener('DOMContentLoaded', function() {
merge.loadState({ day: 'friday' });
}, false);
```
If 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.
```html
YAY! I'm glad you're happy.
Aww! I'm sorry you're sad.
document.addEventListener('DOMContentLoaded', function() {
merge.loadState({ happy: true });
}, false);
```
### Loops: data-merge-repeat
You can loop over elements in an Array using the `data-merge-repeat` and Javascript template substitutions.
```html
document.addEventListener('DOMContentLoaded', function() {
merge.loadState({
items: [{
link: "https://nunn.ink",
label: "Personal Site"
},
{
link: "https://twitter.com/LeviNunnink",
label: "Twitter"
},
{
link: "https://github.com/LeviNunnink",
label: "Github"
}
],
});
}, false);
```
## Contributing
If you have ideas for improvements, feel free to open a PR or an issue and I'll do my best to review it promptly.
## Author
- Levi Nunnink - [@levinunnink](https://twitter.com/levinunnink)
## License
Published under the MIT License.