Add syntax highlighting to code examples

[sabob]

The current example snippets doesn't have much contrast, making it hard to read. One option would be to use a different background color for the snippets or a syntax highlighter.

This PR adds PrismJS syntax highlighting to code examples. I used a Monokai theme which is a contrast with the rest of the site, but there are other themes as well.

In order to get this working I had to upgrade the "marked" package of "handlebars-helper" which comes from "assemble" to a later version which supports a custom Renderer. That way one can override the Renderer.code function to set Prism specific languages on <pre> and <code> tags.

The only way I could figure out how to update the "marked" package was through npm-shrinkwrap.json.

It is much easier to integrate with HighlightJS but it doesn't work well with mustaches (not that PrismJS is perfect)

What do you guys think?

Kind regards

Bob

[evs-chris]

I finally got around to trying this out, but I can't get it to actually run 😞.

I visited a few of the levels of dependency hell before giving up (the npm demon orchestra was playing a lovely grunting symphony). It looks like if we don't manage to do a doc site rewrite in the near future we'll at least need to revamp the current process, because it looks super fragile from how utterly I was able to destroy it whilst playing with this 😆.

[sabob]

Hmm, not sure if it would help, but I'm on Windows 10, node 5.4.0 and I don't have grunt installed globally, only the grunt-cli.

As a quick workaround for 0.8, maybe we should just alter the background of the code snippets to add more contrast for easier reading?

[sabob]

Just tried with a clean checkout of the docs and did:
npm install

Then switched to this PR and npm installed again and got:

TypeError: Cannot read property 'prototype' of undefined

Deleting the node_modules and doing 'npm install' afresh fixed the build for me.

[evs-chris]

I tried wiping out and reloading node_modules and got the same result 😞

As a temporary measure, I bumped the color on code sections to black to increase contrast a bit. It's not perfect, but it's a bit more readable now.

[sabob]

Had a quick look at the current docs build if we can revamp it.

The build uses assemble to convert the yaml, markdown and handlebars templates to html.

Each of these templates have nodejs equivalents so it should be possible to remove assemble (and in turn grunt) and use node itself as the build. Not sure if that is an improvement though ;-)

Personally I don't use grunt/gulp/whatever anymore for builds, as I don't have enough time to master them, and end up fighting them whenever I try and make changes. This issue is a case in point.

Using node by itself doesn't mean less dependencies though, since there are alot of tools one needs to simulate a grunt/gulp, however I've found that the dependencies are more focused on doing one thing rather than multiple things.

For example instead of using assemble to convert yaml, handlebars and markdown one can use the underlying node modules, Handlebars, marked and gray-matter directly.

What do others think? Or is there another static site generator we should look at?

[fskreuz]

We can actually use Gobble (the same tool that builds Ractive) and a few other modules.

I have this proof-of-concept generator based on Gobble that builds my blog. https://github.com/fskreuz/mechanical-pencil Haven't updated it yet, but I use gray-matter to parse the YAML, marked to parse the markdown, handlebars and handlebars-layouts for the templates and gobble-sass for styling. Everything else is custom (see transforms directory).

I once came from Wintersmith. Nice if you already know Jade and CoffeeScript. But those are what drove me away though coz I prefer to write in vanilla JS and HTML. Metalsmith is also neat, much like the Gobble monster I made. Just plug in input through a series of transforms.

[sabob]

@fskreuz your project looks good, well done. Seems a good fit to replace the assemble/grunt combo.