[ocaml-infra] Redesigning OCaml.org - Using Markdown

[Amir Chaudhry]

# Redesigning OCaml.org

Some time ago, I mentioned that we would be looking over the design and
structure of the OCaml.org website [1] and integrating the improvements we've
begun in the OCaml ecosystem, including OCamlot and the documentation work
(see the OCaml Labs news updates to catch-up on everything [2]).  
This message is a summary of the thinking so far and input is welcome.

One of the specific things we've been thinking about is generating pages from
Markdown files, instead of html.  This would make writing content a lot 
easier for contributors and makes maintenance more straightforward.  Of 
course, not every page would be markdown-based and for some it makes sense 
to stick with html (e.g the landing page).  Making a transition like this 
would involve examining the current toolchain and creating new libraries where 
appropriate, but these should be beneficial to the OCamlers in general 
(e.g a good Markdown library).  Below are the broad areas that I think we 
need to consider (but please let me know if I've missed something!)


## Markdown parser/converter

Some discussion of Markdown has already taken place [3], and one of the
issues we recognise is that there isn't really a clear spec for Markdown.  I
know there was a community effort to converge on one [4] but I don't know how
that's going. There's even a tool to help compare different markdown variants
[5].  In the meantime, my preference would be to stick with one of the widely
used versions (e.g GitHub Markdown).


## Templating tool

We also need a way to define templates and to deal with the HTML that the 
markdown converter produces i.e placing it into a webpage with navigation 
and footers as appropriate.  Philippe Wang has been working on a 
general-purpose pre-processor we can use for this purpose (MPP [6]).  
This would also allow us to use macros to include the content of other files 
within a markdown file e.g you could write something like {{import main.ml}} 
in a tutorial and the pre-processor would paste in and format the contents 
of that file.  An example of this would probably be clearer but I wanted to 
be brief in this email.  The workflow in this scenario would be 
`file.md --> [template tool] --> [markdown converter] --> HTML`


## Code evaluation and other customisations

Continuing from the above, as well as simply including code snippets we may 
also want to run them through toplevel and include the output.  This is used 
to great effect on the current site, for example the 100 lines page [7], 99 
problems page [8] and common errors page [9]. We also need to be able to 
generate Tables of Contents automatically, where appropriate.  These are 
obviously solvable (as they have been already) but we should consider where 
and how in the toolchain we want to do this.


## Work in progress

I'm personally attempting to recreate the current site using markdown files 
to see what this process really involves and how robust I can make it.  My 
attempts are in a repo (https://github.com/ocamllabs/ocaml.org-temp) and I'm 
using pandoc for the conversions at the moment.

There's a lot of stuff in preparation for the OCaml ecosystem in general and 
ocaml.org will be an important focal point for a lot of the output. 


[1] http://lists.ocaml.org/pipermail/infrastructure/2013-March/000155.html
[2] http://ocaml.io/news
[3] http://lists.ocaml.org/pipermail/infrastructure/2013-July/000193.html
[4] http://www.codinghorror.com/blog/2012/10/the-future-of-markdown.html
[5] http://johnmacfarlane.net/babelmark2/
[5] http://ocaml.org/tutorials/99problems.html
[6] https://github.com/pw374/MPP-language-blender
[7] http://ocaml.org/taste.html
[8] http://ocaml.org/tutorials/99problems.html
[9] http://ocaml.org/tutorials/common_error_messages.html


Best wishes,
Amir