initial commit

giuseppeg · Sep 15, 2020 · eaa9763 · eaa9763
commit eaa9763
Show file tree

Hide file tree

Showing 23 changed files with 2,107 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+test/.tmp
+.xm/
diff --git a/.npmignore b/.npmignore
@@ -0,0 +1,2 @@
+lib
+test
diff --git a/README.md b/README.md
@@ -0,0 +1,142 @@
+# ₪ xm - extensible HTML
+
+xm is a tiny compiler for HTML that adds
+
+- `<import>` tag to inline external HTML files
+- `<slot>` and `<fill>` tags to define slots and fill them with content
+- `<markdown>` tag to portal into Markdown
+
+<p id="screenshot-1" align="center">
+ <img src="https://user-images.githubusercontent.com/711311/90286174-9de82c80-de75-11ea-89b2-b8e0fd6c7078.png" width="50%" alt="screenshot of an html template with slots">
+</p>
+<p id="screenshot-2" align="center">
+ <img src="https://user-images.githubusercontent.com/711311/90276504-4ee5cb80-de64-11ea-8ebd-99394ff66297.png" width="100%" alt="screenshot of an html page that imports the previous example and fills the slots">
+</p>
+
+xm CLI comes with a **dev mode** that compiles and serves built HTML.
+
+Furthermore xm is built on top of [posthtml-cli](https://posthtml.org/#/cli) and therefore it is [extensible](https://posthtml.org/#/cli?id=options).
+
+## Install
+
+```
+npm i -g xm
+```
+
+### Usage
+
+```
+Usage: xm <command> [options]
+
+Commands:
+
+ dev Compiles HTML files on change and serves the root folder
+ build Compiles the HTML files once
+ help Displays help
+
+Options:
+
+ --root Folder to complile (default ./)
+ --output Output (destination) folder. This is necessary only when using xm build
+ --htmlOnly Compile and copy only the built HTML files
+```
+
+#### `<import>` element
+
+Allows to inline (import) HTML files into the current one.
+
+```html
+<import href="file.html" />
+```
+
+Paths are relative.
+
+```html
+<!-- src/folder/index.html -->
+
+<import href="file.html" />
+<!-- file.html -> src/folder/file.html -->
+```
+
+You can prefix paths with `/` to make them absolute i.e. relative to the `--root` value.
+
+```
+$ xm build --root ./src
+# <import href="file.html" />
+# -> ./src/file.html
+```
+
+#### Importing markdown files
+
+xm supports importing `.md` (markdown) files too. When importing such files the front matter declarations are converted to `fill` elements.
+
+```html
+<style>
+ /* theme */
+</style>
+<import href="README.md" />
+```
+
+💡 This feature can be used to generate styled docs sites for your open source project!
+
+#### `<slot>` and `<fill>` elements
+
+HTML files can define `slot` elements with an attribute `name`. slots can be filled when importing HTML files using the `fill` tag.
+
+```html
+<!-- base.html -->
+
+<!DOCTYPE html>
+<title><slot name="title"></slot></title>
+<main>
+ <slot name="main"></slot>
+</main>
+
+<!-- about.html -->
+
+<import href="base.html">
+ <fill name="title">About</fill>
+ <fill name="main">
+ <h1>About</h1>
+ <p>welcome</p>
+ </fill>
+</import>
+<footer>Unique to this page</footer>
+
+<!-- about.html (compiled with xm) -->
+
+<!DOCTYPE html>
+<title>About</title>
+<main>
+ <h1>About</h1>
+ <p>welcome</p>
+</main>
+```
+
+You can also define a special unnamed `slot` that will be filled with the `import` children that are not `fill` tags:
+
+```html
+<!-- base.html -->
+
+<slot></slot>
+<footer><slot name="footer"></slot></footer>
+
+<!-- about.html -->
+
+<import href="base.html">
+ <fill name="footer">good bye</fill>
+ hello
+ <p>friend</p>
+</import>
+
+<!-- about.html (compiled with xm) -->
+
+hello
+<p>friend</p>
+<footer>good bye</footer>
+```
+
+#### Credits
+
+- [Ivan Demidov](https://twitter.com/Scrum_) for helping me out with PRs and PostHTML
+- [askucher](https://github.com/askucher) for transferring ownership of the `xm` package
diff --git a/docs.html b/docs.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<title>₪ xm</title>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<style>
+ :root {
+ --bg: #383545;
+ --fg: #c7c5ce;
+ --main-bg: #2c2a37;
+ --card-bg: #17161d;
+ --card-fg: #e7e6ea;
+ --accent-fg: #eb9344;
+ }
+ * {
+ box-sizing: border-box;
+ }
+ body {
+ margin: 0;
+ background-color: var(--bg);
+ color: var(--fg);
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+ Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
+ }
+ h2,
+ h3,
+ h4 {
+ margin-top: 2.5em;
+ }
+ a,
+ h2,
+ h3,
+ h4 {
+ font-weight: 400;
+ color: var(--accent-fg);
+ }
+ a code,
+ h1 code,
+ h2 code,
+ h3 code,
+ h4 code {
+ color: var(--accent-fg);
+ }
+ h1 {
+ font-weight: 400;
+ color: var(--card-fg);
+ }
+ main {
+ margin: 0 auto;
+ padding: 1rem 2rem;
+ background-color: var(--main-bg);
+ }
+ @media (min-width: 1000px) {
+ main {
+ max-width: 1000px;
+ padding: 2rem 4rem;
+ }
+ }
+ pre {
+ margin: 2em 0;
+ white-space: pre-wrap;
+ }
+ code {
+ font-family: monaco, monospace;
+ font-size: 0.9em;
+ background-color: var(--card-bg);
+ color: var(--card-fg);
+ padding: 0.1em 0.3em;
+ border-radius: 0.2em;
+ }
+ pre code {
+ display: block;
+ padding: 1em;
+ border-radius: 1em;
+ }
+ #screenshot-1,
+ #screenshot-2 {
+ margin: 0;
+ }
+ .fork {
+ position: absolute;
+ top: 0;
+ right: 0;
+ }
+ footer {
+ text-align: center;
+ margin-top: 2em;
+ }
+ footer a {
+ text-decoration: none;
+ }
+ footer a:hover {
+ text-decoration: underline;
+ }
+</style>
+<main>
+ <div>
+ <import href="README.md" />
+ </div>
+ <footer>Powered by <a href="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/giuseppeg/xm">₪ xm</a></footer>
+ <a class="fork" href="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/giuseppeg/xm"
+ ><img
+ loading="lazy"
+ width="149"
+ height="149"
+ src="https://github.blog/wp-content/uploads/2008/12/forkme_right_orange_ff7600.png?resize=149%2C149"
+ class="attachment-full size-full"
+ alt="Fork me on GitHub"
+ data-recalc-dims="1"
+ /></a>
+</main>