From d257025253b7684bcfb9e2f50dc78a0cad9dd312 Mon Sep 17 00:00:00 2001 From: Rasmus Porsager Date: Mon, 14 Oct 2019 19:06:39 +0200 Subject: [PATCH] Flems in docs (#2348) [skip ci] * Initial addition of flems - fixes #526 * Fix leftover ```js code blocks * Add DOCTYPE * Fix edge & IE11 * Don't show console * Change orientation on mobile * Use mithril@next for playground link * Improve loading and structure * Fix header alignment in IE * Don't rotate logo * Fix conflicts * Allow `js` tags * Fix code block query * Fix Routing section and flems * Fix firefox * Improve flems styling * Improve copy * Fix data -> body in m.request sample * Add flems in docs usage description --- docs/contributing.md | 7 +++ docs/index.md | 125 ++++++++++++++++++++++++++++++++++++------- docs/layout.html | 36 +++++++++++++ docs/style.css | 12 ++++- docs/testing.md | 1 - scripts/lint-docs.js | 7 --- 6 files changed, 160 insertions(+), 28 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index ada5269e..acc2345c 100644 --- a/docs/contributing.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 825190b3..a956bc1e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,12 +67,20 @@ Let's create an HTML file to follow along: ``` -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. -

See the Pen Mithril Scaffold by Pat Cavit (@tivac) on CodePen.

- +```js +var root = document.body -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! +// Your code here + +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 -

See the Pen Mithril Hello World by Pat Cavit (@tivac) on CodePen.

- +```js +var root = document.body + +m.render(root, "Hello World") +``` --- @@ -135,8 +146,16 @@ m("main", [ #### Live Example -

See the Pen Simple Mithril Example by Pat Cavit (@tivac) on CodePen.

- +```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 `` 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 -

See the Pen Mithril Component Example by Pat Cavit (@tivac) on CodePen.

- +```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 -

See the Pen Mithril Routing Example by Pat Cavit (@tivac) on CodePen.

- +```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 -

- See the Pen - Mithril XHR Example by Isiah Meadows (@isiahmeadows) - on CodePen. -

- +```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) +``` --- diff --git a/docs/layout.html b/docs/layout.html index ebfdc338..9f62482e 100644 --- a/docs/layout.html +++ b/docs/layout.html @@ -1,3 +1,4 @@ + @@ -32,6 +33,7 @@ + diff --git a/docs/style.css b/docs/style.css index 60b3a9a3..c52039ae 100644 --- a/docs/style.css +++ b/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); } +} diff --git a/docs/testing.md b/docs/testing.md index d4e5bedb..3f0f1152 100644 --- a/docs/testing.md +++ b/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") }) }) diff --git a/scripts/lint-docs.js b/scripts/lint-docs.js index d622564d..49240e54 100644 --- a/scripts/lint-docs.js +++ b/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) {