I did an interesting experiment with the Rebol Docs repository today.
I forked it and in my copy I setup up the master branch to be the source for Github pages. This ended up giving me a http://brianotto.github.io/reboldocs URL which I then mapped to a sub domain at http://reboldocs.brianotto.com.
I committed the website source I have been working on and then linked the Documentation section to one of the help Markdown files, i.e. http://reboldocs.brianotto.com/insert (which is really insert.MD), and Github now renders any Markdown I add there to HTML, automatically creating a documentation page for me. I had been working on some small code examples, before starting on the website, and so this what you see listed there.
So it appears like we could use the already existing MD files for two purposes, the interpreter help and the website documentation. One thing I did have to do was add HTML comments (i.e. <!–) around the interpreter help section so the website wouldn’t render them. Would it be easy to ignore these by the interpreter?
Anyway, this basically gives us the ability to have URLs named after any of the documents in that repository. Also, the content is controlled by Github, and so the repository can be forked and anyone can contribute using only a markdown editor and sending a PR. There is no need to install Jekyll or the likes.
However, there is still one issue I am looking into and that is the ability to maintain the website header and footer on each of the documentation pages and to have some kind of navigation display. I think you can create a template that all MD files get rendered in, but still looking into this …
What do you think? Do you like this approach?