Change format of docs to the actual language + pseudo-Docco markdown blocks

[daisylb]

So, currently the docs are written in a Markdown file, 95% of which are just a giant GfM code block with a header and footer.

The problem with this is twofold:

1. Most editors (well, Vim and Sublime Text 3, at least) won't syntax highlight inside code blocks properly. This means we have to set the syntax for the whole file to whatever it is we're writing, do weird things to the document so that the introduction doesn't throw off the highlighter too much, and undo those weird things again before each commit.
2. Actually running the code we're writing is a lot more difficult than if it was, say, just a .sql file.

What would be better, IMO, is if we could do something like this:

-- <frontmatter>
-- language: sql
-- et_cetera: et_cetera
-- </frontmatter>
-- <markdown>
-- This bit is parsed as markdown.
-- ## This is a H2
-- [this is a link](https://google.com)
-- </markdown>

-- the rest of this document is put in as a code block
SELECT * FROM myTable;
-- until we get to another markdown block
SELECT col1, col2 FROM myTable;

-- <markdown>
-- this ends the previous code block
-- </markdown>

I have some idea how this could be implemented, but I don't know much Ruby or much about Middleman.

[adambard]

I don't know about you, but I usually just write a .sql (or .whatever) file with comments and then copy+paste it in when it's ready. If you have a dev site up, you can also use the filename frontmatter to provide a download link that you can download and run whenever you want to check up on things.

Don't get me wrong, this would be a nice features. But providing Docco-like facilities to every language would take quite a bit of doing (although integrating with Rouge should make it easier). Although, how badass would it be if every document had a Docco-style layout?

[adambard]

This would have been a monumental undertaking 2 years ago, I feel like this just isn't in the cards :P