Flems in docs (#2348) [skip ci]

docs/contributing.md

@@ -6,6 +6,7 @@
 - [I'm submitting a PR. How do I run tests?](#i'm-submitting-a-pr-how-do-i-run-tests?)
 - [How do I build Mithril?](#how-do-i-build-mithril?)
 - [Is there a style guide?](#is-there-a-style-guide?)
+- [How do I embed live previews in docs?](#how-do-I-embed-live-previews-in-docs?)
 - [Why do tests mock the browser APIs?](#why-do-tests-mock-the-browser-apis?)
 - [Why does Mithril use its own testing framework and not Mocha/Jasmine/Tape?](#why-does-mithril-use-its-own-testing-framework-and-not-mochajasminetape?)
 - [Why doesn't the Mithril codebase use ES6 via Babel or Bublé? Would a PR to upgrade be welcome?](#why-doesn't-the-mithril-codebase-use-es6-via-babel-or-bublé?-would-a-pr-to-upgrade-be-welcome?)
@@ -69,6 +70,12 @@ Spacing and formatting inconsistencies may be fixed after the fact, and we don't
 
 
 
+## How do I embed live previews in docs?
+
+Any code tag marked as `js` and not `javascript` will automatically be wrapped in a live Flems preview.
+
+
+
 ## Why do tests mock the browser APIs?
 
 Most notoriously, because it's impossible to test the router and some side effects properly otherwise. Also, mocks allow the tests to run under Node.js without requiring heavy dependencies like PhantomJS/ChromeDriver/JSDOM.

docs/index.md

@@ -67,12 +67,20 @@ Let's create an HTML file to follow along:
 </body>
 ```
 
-To make things simpler you can fork this pen which already has the latest version of mithril loaded.
+To make things simpler you can try out mithril right here. This is a live playground with Mithril preloaded that - by the way - is also built in Mithril.
 
-<p data-height="265" data-theme-id="light" data-slug-hash="XRrXVR" data-default-tab="js,result" data-user="tivac" data-embed-version="2" data-pen-title="Mithril Scaffold" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/tivac/pen/XRrXVR/">Mithril Scaffold</a> by Pat Cavit (<a href="https://codepen.io/tivac">@tivac</a>) on <a href="https://codepen.io">CodePen</a>.</p>
-<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+
+// Your code here
 
-Mithril is also loaded onto this page already, so you can start poking at the `m` object in the developer console right away if you'd like!
+m.mount(root, {
+	view: function() {
+		return m("h1", "Try me out")
+	}
+})
+```
+> *[Click here to open the sample on flems.io](https://flems.io/mithril@next#0=N4IgZglgNgpgziAXAbVAOwIYFsZJAOgAsAXLKEAGhAGMB7NYmBvEAXwvW10QICsEqdBk2J4s+LLQCuDABQATWtSk4G+AEa15ATwoACYAB00e03oBuEGAHdEesDOrEI9WQEoDxs970AnGMRSviZYsgDkhACMYfphACq+2no4etLEYW5eZqzGrG6UIHAwsE4uaAg8ACyIAExsHCCYOHj41HACNPSMzDxsALqsQA)*
 
 ---
 
@@ -96,8 +104,11 @@ As you can see, you use the same code to both create and update HTML. Mithril au
 
 #### Live Example
 
-<p data-height="265" data-theme-id="light" data-slug-hash="KmPdOO" data-default-tab="js,result" data-user="tivac" data-embed-version="2" data-pen-title="Mithril Hello World" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/tivac/pen/KmPdOO/">Mithril Hello World</a> by Pat Cavit (<a href="https://codepen.io/tivac">@tivac</a>) on <a href="https://codepen.io">CodePen</a>.</p>
-<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+
+m.render(root, "Hello World")
+```
 
 ---
 
@@ -135,8 +146,16 @@ m("main", [
 
 #### Live Example
 
-<p data-height="275" data-theme-id="light" data-slug-hash="gWYade" data-default-tab="js,result" data-user="tivac" data-embed-version="2" data-pen-title="Simple Mithril Example" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/tivac/pen/gWYade/">Simple Mithril Example</a> by Pat Cavit (<a href="https://codepen.io/tivac">@tivac</a>) on <a href="https://codepen.io">CodePen</a>.</p>
-<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+
+m.render(root, [
+    m("main", [
+        m("h1", {class: "title"}, "My first app"),
+        m("button", "A button"),
+    ])
+])
+```
 
 Note: If you prefer `<html>` syntax, [it's possible to use it via a Babel plugin](jsx.md).
 
@@ -206,8 +225,25 @@ If you're wondering about performance, it turns out Mithril is very fast at rend
 
 #### Live Example
 
-<p data-height="300" data-theme-id="light" data-slug-hash="rmBOQV" data-default-tab="js,result" data-user="tivac" data-embed-version="2" data-pen-title="Mithril Component Example" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/tivac/pen/rmBOQV/">Mithril Component Example</a> by Pat Cavit (<a href="https://codepen.io/tivac">@tivac</a>) on <a href="https://codepen.io">CodePen</a>.</p>
-<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+var count = 0 // added a variable
+
+var Hello = {
+    view: function() {
+        return m("main", [
+            m("h1", {
+                class: "title"
+            }, "My first app"),
+            m("button", {
+                onclick: function() {count++}
+            }, count + " clicks")
+        ])
+    }
+}
+
+m.mount(root, Hello)
+```
 
 ---
 
@@ -244,8 +280,36 @@ Also, as you would expect, clicking on the link on the splash page takes you to
 
 #### Live Example
 
-<p data-height="300" data-theme-id="light" data-slug-hash="qmWOvr" data-default-tab="js,result" data-user="tivac" data-embed-version="2" data-pen-title="Mithril Routing Example" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/tivac/pen/qmWOvr/">Mithril Routing Example</a> by Pat Cavit (<a href="https://codepen.io/tivac">@tivac</a>) on <a href="https://codepen.io">CodePen</a>.</p>
-<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+var count = 0
+
+var Hello = {
+    view: function() {
+        return m("main", [
+            m("h1", {
+                class: "title"
+            }, "My first app"),
+            m("button", {
+                onclick: function() {count++}
+            }, count + " clicks"),
+        ])
+    }
+}
+
+var Splash = {
+    view: function() {
+        return m("a", {
+            href: "#!/hello"
+        }, "Enter!")
+    }
+}
+
+m.route(root, "/splash", {
+    "/splash": Splash,
+    "/hello": Hello,
+})
+```
 
 ---
 
@@ -291,12 +355,37 @@ Clicking the button should now update the count.
 
 #### Live Example
 
-<p class="codepen" data-height="265" data-theme-id="light" data-default-tab="js,result" data-user="isiahmeadows" data-slug-hash="aeBZEq" data-preview="true" style="height: 265px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;" data-pen-title="Mithril XHR Example">
-  <span>See the Pen <a href="https://codepen.io/isiahmeadows/pen/aeBZEq/">
-  Mithril XHR Example</a> by Isiah Meadows (<a href="https://codepen.io/isiahmeadows">@isiahmeadows</a>)
-  on <a href="https://codepen.io">CodePen</a>.</span>
-</p>
-<script async src="https://static.codepen.io/assets/embed/ei.js"></script>
+```js
+var root = document.body
+var count = 0
+
+var increment = function() {
+    m.request({
+        method: "PUT",
+        url: "//rem-rest-api.herokuapp.com/api/tutorial/1",
+        body: {count: count + 1},
+        withCredentials: true,
+    })
+    .then(function(data) {
+        count = parseInt(data.count)
+    })
+}
+
+var Hello = {
+    view: function() {
+        return m("main", [
+            m("h1", {
+                class: "title"
+            }, "My first app"),
+            m("button", {
+                onclick: increment
+            }, count + " clicks"),
+        ])
+    }
+}
+
+m.mount(root, Hello)
+```
 
 ---
 

docs/layout.html

@@ -1,3 +1,4 @@
+<!DOCTYPE html>
 <html>
 	<head>
 		<meta charset="UTF-8" />
@@ -32,13 +33,48 @@ <h1><img src="logo.svg"> Mithril <small>[version]</small></h1>
 		<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/components/prism-jsx.min.js"></script>
 		<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/components/prism-diff.min.js"></script>
 		<script src="https://unpkg.com/mithril@[version]/mithril.js" async></script>
+		<script src="https://flems.io/flems.html" id="flems" defer></script>
 		<script>
 		document.querySelector(".hamburger").onclick = function() {
 			document.body.className = document.body.className === "navigating" ? "" : "navigating"
 			document.querySelector("h1 + ul").onclick = function() {
 				document.body.className = ''
 			}
 		}
+		document.getElementById("flems").onload = function() {
+			var systemFonts = [
+				"body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; }",
+				"body { height: 100%; overflow:hidden; display:flex; justify-content: center; align-items:center; }"
+			].join("")
+			;[].forEach.call(document.querySelectorAll("pre code.language-js"), function(el) {
+				el = el.parentNode
+
+				var div = document.createElement("div")
+				window.Flems(div, {
+					middle        : 60,
+					editable      : true,
+					toolbar       : false,
+					shareButton   : true,
+					console       : false,
+					autoHeight    : true,
+					files: [{
+						name: ".js",
+						content: el.textContent
+					}, {
+						name: ".css",
+						content: systemFonts
+					}],
+					links: [{
+						name: "mithril",
+						type: "script",
+						url: "https://unpkg.com/mithril@[version]/mithril.js"
+					}]
+				}, "https://flems.io/flems.html")
+
+				el.parentNode.insertBefore(div, el)
+				el.parentNode.removeChild(el)
+			})
+		}
 		</script>
 	</body>
 </html>

docs/style.css

@@ -1,6 +1,6 @@
 body {background:white;-webkit-text-size-adjust: 100%;}
 body,table,h5 {font-weight:normal;font-size:16px;font-family:'Open Sans',sans-serif;}
-header,main {margin:auto;max-width:1000px;}
+header,main {max-width:1000px;}
 header section {position:absolute;width:250px;}
 nav a {border-left:1px solid #ddd;padding:0 10px;}
 nav a:first-child {border:0;padding-left:0;}
@@ -28,7 +28,7 @@ h2 {font-size:22px;margin:45px 0 15px;}
 h3 {font-size:20px;margin:45px 0 15px;}
 h4 {font-size:18px;margin:30px 0 15px;}
 h5 {font-weight:bold;margin:15px 0 15px;}
-h1 img {transform:rotate(180deg);vertical-align:middle;width:20px;}
+h1 img {vertical-align:middle;width:20px;}
 h1 small {font-size:16px;}
 h2 a,h3 a,h4 a,h5 a,
 h2 a:hover,h3 a:hover,h4 a:hover,h5 a:hover,
@@ -95,3 +95,11 @@ h1 + ul strong + ul {border-left:3px solid #1e5799;}
 .token.selector,.token.attr-name,.token.string,.token.builtin {color:#690;}
 .token.atrule,.token.attr-value,.token.punctuation,.token.keyword {color:#1e5799;}
 .token.regex,.token.important {color:#e90;}
+
+/* flems theming */
+.flems main { margin: 0; max-width: auto; }
+.flems { margin: 20px 0; max-height: 400px; }
+.flems .runtime { border: 1px solid #ddd; }
+@media (max-width: 500px) {
+	.flems { min-height: calc(100vw * 1.3); }
+}

docs/testing.md

@@ -77,7 +77,6 @@ var MyComponent = require("../my-component.js")
 o.spec("MyComponent", function() {
 	o("things are working", function() {
 		var out = mq(MyComponent, {text: "What a wonderful day to be alive!"})
-
 		out.should.contain("day")
 	})
 })

scripts/lint-docs.js

@@ -106,7 +106,6 @@ class LintRenderer extends marked.Renderer {
 			}
 		}
 		this._ensureCodeIsHighlightable()
-		this._ensureCodeHasConsistentTag()
 		this._ensureCodeIsSyntaticallyValid()
 		this._ensureCommentStyle()
 	}
@@ -135,12 +134,6 @@ class LintRenderer extends marked.Renderer {
 		}
 	}
 
-	_ensureCodeHasConsistentTag() {
-		if (this._lang === "js") {
-			this._emit("JS code block has wrong language tag", this._block())
-		}
-	}
-
 	_ensureCodeIsSyntaticallyValid() {
 		if (!this.lang || !(/^js$|^javascript$/).test(this._lang)) return
 		if (this._error != null) {