docs tweaks
This commit is contained in:
Leo
parent
1780985036
commit
aee13901d8
52 changed files with 8830 additions and 47 deletions
|
|
@ -1,6 +1,7 @@
|
|||
# Change log
|
||||
|
||||
- [Migrating from v0.2.x](#migrating-from-v02x)
|
||||
- [Older docs](http://mithril.js.org/archive/v0.2.5/change-log.html)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -200,8 +200,8 @@ var Login = {
|
|||
login: function() {/*...*/},
|
||||
view: function() {
|
||||
return m(".login", [
|
||||
m("input[type=text]", {oninput: m.withAttr("value", this.setUsername.bind(this)), this.username}),
|
||||
m("input[type=password]", {oninput: m.withAttr("value", this.setPassword.bind(this)), this.password}),
|
||||
m("input[type=text]", {oninput: m.withAttr("value", this.setUsername.bind(this)), value: this.username}),
|
||||
m("input[type=password]", {oninput: m.withAttr("value", this.setPassword.bind(this)), value: this.password}),
|
||||
m("button", {disabled: !this.canSubmit(), onclick: this.login}, "Login"),
|
||||
])
|
||||
}
|
||||
|
|
@ -214,7 +214,7 @@ Right away, we see that sharing the `username` and `password` fields from this c
|
|||
|
||||
It makes more sense to refactor this component and pull the state code out of the component and into the application's data layer. This can be as simple as creating a new module:
|
||||
|
||||
```
|
||||
```javascript
|
||||
// models/Auth.js
|
||||
// PREFER
|
||||
var Auth = {
|
||||
|
|
@ -237,7 +237,7 @@ module.exports = Auth
|
|||
|
||||
Then, we can clean up the component:
|
||||
|
||||
```
|
||||
```javascript
|
||||
// views/Login.js
|
||||
// PREFER
|
||||
var Auth = require("../models/Auth")
|
||||
|
|
@ -245,8 +245,8 @@ var Auth = require("../models/Auth")
|
|||
var Login = {
|
||||
view: function() {
|
||||
return m(".login", [
|
||||
m("input[type=text]", {oninput: m.withAttr("value", Auth.setUsername), Auth.username}),
|
||||
m("input[type=password]", {oninput: m.withAttr("value", Auth.setPassword), Auth.password}),
|
||||
m("input[type=text]", {oninput: m.withAttr("value", Auth.setUsername), value: Auth.username}),
|
||||
m("input[type=password]", {oninput: m.withAttr("value", Auth.setPassword), value: Auth.password}),
|
||||
m("button", {disabled: !Auth.canSubmit(), onclick: Auth.login}, "Login"),
|
||||
])
|
||||
}
|
||||
|
|
|
|||
|
|
@ -12,19 +12,19 @@ If you're reading this page, you probably have used other frameworks to build ap
|
|||
|
||||
## Why not [insert favorite framework here]?
|
||||
|
||||
The reality is that most modern frameworks are fast, well-suited to build complex applications, and highly maintainable if you know how to use them effectively. There are examples of highly complex applications in the wild using just about every popular framework: Udemy uses Angular, AirBnB uses React, Gitlab uses Vue, Guild Wars 2 uses Mithril (yes, inside the game!). Clearly, these are all production-quality frameworks.
|
||||
The reality is that most modern frameworks are fast, well-suited to build complex applications, and maintainable if you know how to use them effectively. There are examples of highly complex applications in the wild using just about every popular framework: Udemy uses Angular, AirBnB uses React, Gitlab uses Vue, Guild Wars 2 uses Mithril (yes, inside the game!). Clearly, these are all production-quality frameworks.
|
||||
|
||||
As a rule of thumb, if your team is already heavily invested in another framework/library/stack, it makes more sense to stick with it, unless your team agrees that there's a very strong reason to justify a costly rewrite.
|
||||
|
||||
However, if you're starting something new, do consider giving Mithril a try, if nothing else, to see how much value Mithril adopters have been getting out of 8kb (gzipped) of code. Mithril is used by many well-known companies (e.g. Vimeo, Nike, Fitbit), and it powers large open-sourced platforms too (e.g. Lichess, Flarum).
|
||||
However, if you're starting something new, do consider giving Mithril a try, if nothing else, to see how much value Mithril adopters have been getting out of 8kb (gzipped) of code. Mithril is used by many well-known companies (e.g. Vimeo, Nike, Fitbit), and it powers large open-sourced platforms too (e.g. Lichess, Flarum).
|
||||
|
||||
---
|
||||
|
||||
## Why use Mithril?
|
||||
|
||||
In one sentence: because **Mithril is pragmatic**. The 10 minutes [guide](introduction.md) is a good example: that's how long it takes to get working knowledge of Mithril's virtual DOM system, XHR and routing tools.
|
||||
In one sentence: because **Mithril is pragmatic**. The 10 minutes [guide](index.md) is a good example: that's how long it takes to learn components, XHR and routing - and that's just about the right amount of knowledge needed to build useful applications.
|
||||
|
||||
Mithril is all about getting work done efficiently. Doing file uploads? [The docs show you how](request.md#file-uploads). Authentication? [Documented too](route.md#authentication). Exit animations? [You got it](animation.md). No extra libraries, no magic.
|
||||
Mithril is all about getting meaningful work done efficiently. Doing file uploads? [The docs show you how](request.md#file-uploads). Authentication? [Documented too](route.md#authentication). Exit animations? [You got it](animation.md). No extra libraries, no magic.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -42,7 +42,7 @@ React and Mithril share a lot of similarities. If you already learned React, you
|
|||
|
||||
The most obvious difference between React and Mithril is in their scope. React is a view library, so a typical React-based application relies on third-party libraries for routing, XHR and state management. Using a library oriented approach allows developers to customize their stack to precisely match their needs. The not-so-nice way of saying that is that React-based architectures can vary wildly from project to project, and that those projects are that much more likely to cross the 1MB size line.
|
||||
|
||||
Mithril has built-in modules for common necessities such as routing and XHR, and the [guide](simple-application.md) demonstrates idiomatic usage. This approach is preferable for teams that value consistency and ease of onboarding.
|
||||
Mithril has built-in modules for common necessities such as routing and XHR, and the [guide](simple-application.md) demonstrates idiomatic usage. This approach is preferable for teams that value consistency and ease of onboarding.
|
||||
|
||||
#### Performance
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ Idiomatic React requires working knowledge of JSX and its caveats, and therefore
|
|||
|
||||
React documentation is clear and well written, and includes a good API reference, tutorials for getting started, as well as pages covering various advanced concepts. Unfortunately, since React is limited to being only a view library, its documentation does not explore how to use React idiomatically in the context of a real-life application. As a result, there are many popular state management libraries and thus architectures using React can differ drastically from company to company (or even between projects).
|
||||
|
||||
Mithril documentation also includes [introductory](introduction.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference.
|
||||
Mithril documentation also includes [introductory](index.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference.
|
||||
|
||||
Mithril documentation also demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries.
|
||||
|
||||
|
|
@ -161,7 +161,7 @@ With that being said, Angular has a lot more concepts to learn than Mithril. It
|
|||
|
||||
Angular 2 documentation provides an extensive introductory tutorial, and another tutorial that implements an application. It also has various guides for advanced concepts, a cheatsheet and a style guide. Unfortunately, at the moment, the API reference leaves much to be desired. Several APIs are either undocumented or provide no context for what the API might be used for.
|
||||
|
||||
Mithril documentation includes [introductory](introduction.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference.
|
||||
Mithril documentation includes [introductory](index.md) [tutorials](simple-application.md), pages about advanced concepts, and an extensive API reference section, which includes input/output type information, examples for various common use cases and advice against misuse and anti-patterns. It also includes a cheatsheet for quick reference.
|
||||
|
||||
Mithril documentation also demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries.
|
||||
|
||||
|
|
@ -213,4 +213,4 @@ However, due to Vue's many-ways-to-do-one-thing approach, some things may not be
|
|||
|
||||
Mithril documentation typically errs on the side of being overly thorough if a topic involves things outside of the scope of Mithril. For example, when a topic involves a 3rd party library, Mithril documentation walks through the installation process for the 3rd party library. Mithril documentation also often demonstrates simple, close-to-the-metal solutions to common use cases in real-life applications where it's appropriate to inform a developer that web standards may be now on par with larger established libraries.
|
||||
|
||||
Mithril's tutorials also cover a lot more ground than Vue's: the [Vue tutorial](https://vuejs.org/v2/guide/#Getting-Started) finishes with a static list of foodstuff. [Mithril's 10 minute guide](introduction.md) covers the majority of its API and goes over key aspects of real-life applications, such as fetching data from a server and routing (and there's a [longer, more thorough tutorial](simple-application.md) if that's not enough).
|
||||
Mithril's tutorials also cover a lot more ground than Vue's: the [Vue tutorial](https://vuejs.org/v2/guide/#Getting-Started) finishes with a static list of foodstuff. [Mithril's 10 minute guide](index.md) covers the majority of its API and goes over key aspects of real-life applications, such as fetching data from a server and routing (and there's a [longer, more thorough tutorial](simple-application.md) if that's not enough).
|
||||
|
|
|
|||
|
|
@ -3,10 +3,10 @@ var path = require("path")
|
|||
var marked = require("marked")
|
||||
var layout = fs.readFileSync("./docs/layout.html", "utf-8")
|
||||
var version = JSON.parse(fs.readFileSync("./package.json", "utf-8")).version
|
||||
try {fs.mkdirSync("docs/archive/")} catch (e) {}
|
||||
try {fs.mkdirSync("docs/archive/" + version)} catch (e) {}
|
||||
try {fs.mkdirSync("docs/archive/" + version + "/lib")} catch (e) {}
|
||||
try {fs.mkdirSync("docs/archive/" + version + "/lib/prism")} catch (e) {}
|
||||
try {fs.mkdirSync("archive")} catch (e) {}
|
||||
try {fs.mkdirSync("archive/v" + version)} catch (e) {}
|
||||
try {fs.mkdirSync("archive/v" + version + "/lib")} catch (e) {}
|
||||
try {fs.mkdirSync("archive/v" + version + "/lib/prism")} catch (e) {}
|
||||
|
||||
var guides = fs.readFileSync("docs/guides.md", "utf-8")
|
||||
var methods = fs.readFileSync("docs/methods.md", "utf-8")
|
||||
|
|
@ -47,11 +47,10 @@ function generate(pathname) {
|
|||
.replace(/<h5 id="([^"]+?)">([^<]+?)<\/h5>/gim, function(match, id, text) { // fix anchors
|
||||
return "<h5 id=\"" + text.toLowerCase().replace(/\.|\[|\]|"|\//g, "") + "\">" + text + "</h5>"
|
||||
})
|
||||
fs.writeFileSync("docs/archive/" + version + "/" + outputFilename.replace(/^docs\//, ""), html, "utf-8")
|
||||
fs.writeFileSync("archive/v" + version + "/" + outputFilename.replace(/^docs\//, ""), html, "utf-8")
|
||||
}
|
||||
else {
|
||||
fs.writeFileSync("docs/archive/" + version + "/" + pathname.replace(/^docs\//, ""), fs.readFileSync(pathname, "utf-8"), "utf-8")
|
||||
else if (!pathname.match(/lint|generate/)) {
|
||||
fs.writeFileSync("archive/v" + version + "/" + pathname.replace(/^docs\//, ""), fs.readFileSync(pathname, "utf-8"), "utf-8")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
- Tutorials
|
||||
- [Installation](installation.md)
|
||||
- [Introduction](introduction.md)
|
||||
- [Introduction](index.md)
|
||||
- [Tutorial](simple-application.md)
|
||||
- Resources
|
||||
- [JSX](jsx.md)
|
||||
|
|
|
|||
|
|
@ -12,15 +12,46 @@
|
|||
|
||||
### What is Mithril?
|
||||
|
||||
Mithril is a client-side Javascript framework for building Single Page Applications.
|
||||
Mithril is a modern client-side Javascript framework for building Single Page Applications.
|
||||
It's small (< 8kb gzip), fast and provides routing and XHR utilities out of the box.
|
||||
|
||||
<style>
|
||||
@keyframes grow {
|
||||
from {transform:scaleX(0)}
|
||||
to {transform:scaleX(100%)}
|
||||
}
|
||||
</style>
|
||||
<div style="display:flex;margin:0 0 30px;">
|
||||
<div style="width:50%;">
|
||||
<h5>Download size</h5>
|
||||
<small>Mithril (8kb)</small>
|
||||
<div style="animation:grow 0.08s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:4%;"></div>
|
||||
<small style="color:#aaa;">Vue + Vue-Router + Vuex + fetch (40kb)</small>
|
||||
<div style="animation:grow 0.4s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:20%"></div>
|
||||
<small style="color:#aaa;">React + React-Router + Redux + fetch (64kb)</small>
|
||||
<div style="animation:grow 0.64s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:32%"></div>
|
||||
<small style="color:#aaa;">Angular (135kb)</small>
|
||||
<div style="animation:grow 1.35s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:68%"></div>
|
||||
</div>
|
||||
<div style="width:50%;">
|
||||
<h5>Performance</h5>
|
||||
<small>Mithril (6.4ms)</small>
|
||||
<div style="animation:grow 0.64s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:24%;"></div>
|
||||
<small style="color:#aaa;">Vue (9.8ms)</small>
|
||||
<div style="animation:grow 0.98s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:40%"></div>
|
||||
<small style="color:#aaa;">React (12.1ms)</small>
|
||||
<div style="animation:grow 1.21s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:48%"></div>
|
||||
<small style="color:#aaa;">Angular (11.5ms)</small>
|
||||
<div style="animation:grow 1.15s;background:#1e5799;height:3px;margin:0 10px 10px 0;transform-origin:0;width:44%"></div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Mithril is used by companies like Vimeo and Nike, and open source platforms like Lichess.
|
||||
|
||||
If you are an experienced developer and want to know how Mithril compares to other frameworks, see the [framework comparison](framework-comparison.md) page.
|
||||
|
||||
---
|
||||
|
||||
Note: This introduction assumes you have basic level of Javacript knowledge. If you don't, there are many great resources to learn. [Speaking Javascript](http://speakingjs.com/es5/index.html) is a good e-book for absolute beginners. If you're already familiar with other programming languages, the [Eloquent Javascript](http://eloquentjavascript.net/) e-book might be more suitable for you. [Codecademy](https://www.codecademy.com/learn/javascript) is another good resource that emphasizes learning via interactivity.
|
||||
|
||||
### Getting started
|
||||
|
||||
The easiest way to try out Mithril is to include it from a CDN, and follow this tutorial. It'll cover the majority of the API surface (including routing and XHR) but it'll only take 10 minutes.
|
||||
|
|
@ -142,7 +173,8 @@ var Hello = {
|
|||
view: function() {
|
||||
return m("main", [
|
||||
m("h1", {class: "title"}, "My first app"),
|
||||
m("button", {onclick: function() {count++}}, count + " clicks"), // changed this line
|
||||
// changed the next line
|
||||
m("button", {onclick: function() {count++}}, count + " clicks"),
|
||||
])
|
||||
}
|
||||
}
|
||||
|
|
@ -11,7 +11,7 @@
|
|||
<section>
|
||||
<h1>Mithril <small>[version]</small></h1>
|
||||
<nav>
|
||||
<a href="introduction.html">Guide</a>
|
||||
<a href="index.html">Guide</a>
|
||||
<a href="api.html">API</a>
|
||||
<a href="https://gitter.im/lhorie/mithril.js">Chat</a>
|
||||
<a href="https://github.com/lhorie/mithril.js">Github</a>
|
||||
|
|
@ -27,4 +27,4 @@
|
|||
</main>
|
||||
<script src="lib/prism/prism.js"></script>
|
||||
</body>
|
||||
</html
|
||||
</html
|
||||
|
|
|
|||
29
docs/lint.js
29
docs/lint.js
|
|
@ -37,7 +37,7 @@ function ensureCodeIsSyntaticallyValid(file, data) {
|
|||
function ensureCodeIsRunnable(file, data) {
|
||||
var codeBlocks = data.match(/```javascript(.|\n|\r)*?```/gim) || []
|
||||
var code = codeBlocks.map(function(block) {return block.slice(13, -3)}).join(";")
|
||||
|
||||
|
||||
//stubs
|
||||
var silentConsole = {log: function() {}}
|
||||
var fetch = function() {
|
||||
|
|
@ -54,7 +54,7 @@ function ensureCodeIsRunnable(file, data) {
|
|||
if (dep.indexOf("mithril/ospec/ospec") === 0) return global.o
|
||||
if (dep.indexOf("mithril/stream") === 0) return global.stream
|
||||
if (dep === "mithril") return global.m
|
||||
|
||||
|
||||
if (dep === "../model/User") return {
|
||||
list: [],
|
||||
current: {},
|
||||
|
|
@ -74,7 +74,6 @@ function ensureCodeIsRunnable(file, data) {
|
|||
})
|
||||
}
|
||||
catch (e) {console.log(file + " - javascript code cannot run\n\n" + e.stack + "\n\n" + code + "\n\n---\n\n")}
|
||||
|
||||
}
|
||||
|
||||
function ensureCommentStyle(file, data) {
|
||||
|
|
@ -86,7 +85,7 @@ function ensureCommentStyle(file, data) {
|
|||
}
|
||||
|
||||
function ensureLinkIsValid(file, data) {
|
||||
var links = data.match(/\]\(([^\)]+)\)/gim)
|
||||
var links = data.match(/\]\(([^\)]+?)\)/gim) || []
|
||||
links.forEach(function(match) {
|
||||
var link = match.slice(2, -1)
|
||||
var path = link.match(/[\w-]+\.md/)
|
||||
|
|
@ -110,37 +109,37 @@ function initMocks() {
|
|||
|
||||
//routes consumed by request.md
|
||||
global.window.$defineRoutes({
|
||||
"GET /api/v1/users": function(request) {
|
||||
"GET /api/v1/users": function() {
|
||||
return {status: 200, responseText: JSON.stringify([{name: ""}])}
|
||||
},
|
||||
"GET /api/v1/users/search": function(request) {
|
||||
"GET /api/v1/users/search": function() {
|
||||
return {status: 200, responseText: JSON.stringify([{id: 1, name: ""}])}
|
||||
},
|
||||
"GET /api/v1/users/1/projects": function(request) {
|
||||
"GET /api/v1/users/1/projects": function() {
|
||||
return {status: 200, responseText: JSON.stringify([{id: 1, name: ""}])}
|
||||
},
|
||||
"GET /api/v1/todos": function(request) {
|
||||
"GET /api/v1/todos": function() {
|
||||
return {status: 200, responseText: JSON.stringify([])}
|
||||
},
|
||||
"PUT /api/v1/users/1": function(request) {
|
||||
"PUT /api/v1/users/1": function() {
|
||||
return {status: 200, responseText: request.query.callback ? request.query.callback + "([])" : "[]"}
|
||||
},
|
||||
"POST /api/v1/upload": function(request) {
|
||||
"POST /api/v1/upload": function() {
|
||||
return {status: 200, responseText: JSON.stringify([])}
|
||||
},
|
||||
"GET /files/icon.svg": function(request) {
|
||||
"GET /files/icon.svg": function() {
|
||||
return {status: 200, responseText: "<svg></svg>"}
|
||||
},
|
||||
"GET /files/data.csv": function(request) {
|
||||
"GET /files/data.csv": function() {
|
||||
return {status: 200, responseText: "a,b,c"}
|
||||
},
|
||||
"GET /api/v1/users/123": function(request) {
|
||||
"GET /api/v1/users/123": function() {
|
||||
return {status: 200, responseText: JSON.stringify({id: 123})}
|
||||
},
|
||||
"GET /api/v1/users/foo:bar": function(request) {
|
||||
"GET /api/v1/users/foo:bar": function() {
|
||||
return {status: 200, responseText: JSON.stringify({id: 123})}
|
||||
},
|
||||
"GET /files/image.svg": function(request) {
|
||||
"GET /files/image.svg": function() {
|
||||
return {status: 200, responseText: "<svg></svg>"}
|
||||
},
|
||||
})
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ h4 {font-size:18px;margin:30px 0 15px;}
|
|||
h5 {font-weight:bold;margin:15px 0 15px;}
|
||||
h1 small {font-size:16px;}
|
||||
p {margin:0 0 15px;}
|
||||
pre,code {background:#eee;font-family:monospace;}
|
||||
pre,code {background:#eee;font-family:monospace;font-size:14px;}
|
||||
pre {border-left:3px solid #1e5799;overflow:auto;padding:10px 20px;}
|
||||
code {border:1px solid #ddd;display:inline-block;margin:0 0 1px;padding:3px;white-space:pre;}
|
||||
pre code {border:0;margin:0;padding:0;}
|
||||
|
|
@ -22,7 +22,7 @@ thead tr,tbody tr:nth-child(even) {background:#f3f3f3;}
|
|||
tr {border-bottom:1px solid #eee;}
|
||||
th {text-align:left;}
|
||||
th,td {padding:3px 10px;vertical-align:top;}
|
||||
a {color:#1e5799;display:inline-block;text-decoration:none;}
|
||||
a {color:#1e5799;text-decoration:none;}
|
||||
a:hover {text-decoration:underline;}
|
||||
hr {border:0;border-bottom:1px solid #ddd;margin:30px 0;}
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ h1 + ul {margin:40px 0 0 -270px;padding:0;position:absolute;width:250px;}
|
|||
h1 + ul + hr {display:none;}
|
||||
h1 + ul li {list-style:none;margin:0;padding:0;}
|
||||
h1 + ul li:last-child {border-bottom:0;}
|
||||
h1 + ul ul {margin:0 0 10px;padding:0 0 0 15px;}
|
||||
h1 + ul ul {margin:0 0 2px;padding:0 0 0 15px;}
|
||||
h1 + ul ul li {border:0;}
|
||||
h1 + ul strong + ul {border-left:3px solid #1e5799;}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue