Prototype markdown based handout template system.

[flukeout]

Now that we've basically settled on the format and styling of the handouts (Example - from #11) - let's figure out how to make the content editable as markdown. The advantages of this are...

• Markup is easier to work with for non-technical contributors
• The underlying content will be readable and editable via the github interface

The General Idea Our goal is to host each handout as a separate markdown file on Github but also to serve them as pretty, styled HTML & CSS documents via some service we come up with. This service will parse the markdown and generate the appropriate HTML - to help this along, we will probably have to include classnames in the markdown, ie. {.description}.

cc @acabunoc

[abbycabs]

After reading a bit, I think Jekyll hosted on gh-pages maybe be a good idea:

https://help.github.com/articles/using-jekyll-with-pages/

We would store markdown files on the gh-pages branch with some front matter (metadata): https://help.github.com/articles/using-jekyll-with-pages/#front-matter-is-required

Along with a _layouts folder that uses the liquid template language: http://jekyllrb.com/docs/templates/

Then, github runs jekyll and generates the html that gets served on gh-pages

[flukeout]

@acabunoc Check out what I did for the Clubs template work...

• Live Template - http://flukeout.github.io/master-template/clubs-markdown/#introduction
• Markdown Source - https://github.com/flukeout/master-template/blob/master/clubs-markdown/content.md

All of the content for the guide lives in content.md and is converted into HTML. The left-side navigation is auto-generated based on the top-level headings in the markdown file, which reduces the clutter in the markdown.

This particular clubs template is pretty simple so converting it is easy. The Science template has some more complex layouts and elements - but this is a good starting point. I'll dig in to see if we can do something similar for Science.

I'm using PageDown client-side to convert the markdown. There are some add-ons for it that will let us pass attributes (like classnames and stuff) if we need it.

[flukeout]

@acabunoc Okay check this out

• Content - https://github.com/flukeout/master-template/blob/master/science-markdown/content.md
• Dynamic HTML Version - http://flukeout.github.io/master-template/science-markdown/

It's still a little rough around the edges and might be a bit frail, but it's starting to get the job done. The best part is that the markdown file itself is well organized and easy-to-read.

The "fragility" right now comes form relying on the various headers to be specific keywords, otherwise the template won't know to format the three-columns-across layout the way it does, for example.

[auremoser]

so rad, had some really lovely feedback on the professional quality of our workshop materials, thanks @flukeout + @acabunoc

githug

[abbycabs]

Re-opening since we haven't finalized how we're going to use markdown on our templates!

@flukeout

Content - https://github.com/flukeout/master-template/blob/master/science-markdown/content.md
Dynamic HTML Version - http://flukeout.github.io/master-template/science-markdown/

This looks amazing! One tiny thing, the sidebar doesn't seem to update as you scroll down anymore. Other than that, it looks identical to the html version (from what I can see) :tada: