Embed a working example server

[tolmasky]

I'd like to propose adding a runnable embedded Koa server into the documentation, to make it easy for people to play around with Koa and see how it works. Basically, both the initial hello world example and the following logging example are completely editable and testable right from the browser, which ends up looking like this:

This is powered by RunKit (which I helped create), which is creating a virtual server on demand behind the scenes. And if for whatever reason RunKit goes down, the example will fall back to just looking as it does now. The goal we are trying to accomplish is to make libraries immediately usable, so people can start programming right from the documentation, not having to first install etc etc.

Lodash has been using RunKit on their documentation for about a year now, and Express recently incorporated RunKit into their Getting Started example as well. https://expressjs.com/en/starter/hello-world.html . Would love to see the same here, and I am happy to make any changes as necessary.

A small note: the change set is a bit larger than it would seem to need because I upgraded jade to pug. The version of jade being used to create these docs was quite old and has since been renamed to pug. I added a "runkit-endpoint" markdown code language that can be used to turn any code snippet into one of these live examples. I'm also happy to make the corresponding documentation commit on Koa's git repo, but wasn't sure how that should be coordinated.

[jonathanong]

could you rename options.js to pug-options.js to make the purpose more self-evident?

[tolmasky]

Yup, let me know if you'd like any other changes.

[tolmasky]

I've gone ahead and fixed the conflict that came about from merging the highlight change. Additionally, I moved code highlighting code to make instead of having it happen on the client.

I realized after the fact that the docs are actually pulled from online, so this pull request requires a matching pull request in the main repo to activate the server stuff: koajs/koa#1031

Basically, any example you want to make a server, you just add <!-- runkit:endpoint --> to.

[tolmasky]

Just wanted to check in to see if there's anything left to do. To recap, the last change:

1. Modified the filename.
2. Fixed the conflict with the highlighting code that was merged in
3. Coordinated with the main repo for docs.

[tolmasky]

I've now also fixed the conflict with the latest change.

[tolmasky]

Just checking in on this, anything else needed?

[tolmasky]

Any update on this?

[tolmasky]

Just checking in again.

[niftylettuce]

@tolmasky is there any way you could fix the merge conflicts so we can get this merged in?

[tolmasky]

OK, I believe I have now fixed the merge conflicts. To summarize the various changes:

1. The actual content of the change: to make the two examples editable and "live", just like on express' documentation.
2. Update jade to pug -- jade was simply renamed pug -- that's why Koa is currently using a 3 year old version of jade and can't receive further updates as long as it remains pinned to "jade". While this looks like a "framework change" in the diff, it's identical to just updating jade to the latest version. All the templates remain .jade, etc.
3. Since the build step now processes the code examples in order to be able to make the examples live, the highlight.js step is done here during "build-time" as well instead of happening client-side on load. This means the koa website should get faster as you are 1) delivering less resources (no highlight.js file) and 2) don't run the highlight.js script on load.

IMPORTANT This change includes the updated index.html to go along with it, but in order to "continue" having the examples be live on subsequent builds, the associated PR koajs/koa#1031 must be taken as well. This is because koajs.com repo pulls from the main repo to grab the documentation, and the way "live examples" are handled is with a special marker so that you can tag ANY example as live. If you view that PR, it is super trivial, it is merely marking the two first examples as live.

[tolmasky]

Another quick note about the IMPORTANT note above. Neither change blocks the other, this one accepted now will simply "degrade" to the old non-live behavior (but keep the performance and version advantages), until the subsequent change on the main Koa repo is taken in.

updated commit

[niftylettuce]

merged

[niftylettuce]

just tested as well on koajs.com, looks good! thanks @tolmasky

[tolmasky]

Great, thanks! Do you happen to also have commit privileges for the corresponding commit on the main repo, or should I just bump that myself to get them to take it in? koajs/koa#1031