Convert to Jekyll Website

[adamvoss]

#I am not really expecting that this would be merged since it would mean shutting down your ReadTheDocs pages. However, I thought I should at least make you aware of it.

The ReadTheDocs website wasn't working out for me, so I converted everything for hosting on GitHub Pages: https://adamvoss.github.io/openrecipeformat/

[techhat]

Hi @adamvoss. You're right, I'm not going to merge this, in anything but RST format. It's not because I have any particular preference for readthedocs; that site is clearly not appropriate for this project. But I really dislike the GitHub wiki, and I've never been a fan of the MD format. I would like to merge the other stuff though (.gitignore, ruby stuff, etc).

[adamvoss]

I agree about the GitHub wiki. I think it was important in the early days of GitHub, but now GitHub Pages is pretty much always a better solution.

With respect to Markdown, I perhaps am not discerning enough. Markdown is pretty ubiquitous on sites I encounter (GitHub, StackOverfow, Discourse, ...) and has ample tooling, which makes reStructuredText just "something else to learn." From a practical standpoint, GitHub Pages does not support reStructuredText so another solution would be needed. Travis CI could be used to build the static site and publish the result to the gh-pages branch. Really any static site generator with RST support could be used at that point. A plugin adding RST support to Jekyll exists; so, assuming it works, Jekyll would be an option.

[techhat]

I use RST on a pretty regular basis (in particular with Sphinx), and MD almost never. I'm not used to it, and the times I've had to use it, it generally seems to fail me. This could just be due to my own inexperience, but that would put MD squarely in the category of "something else for me to learn". On this point, it would seem we are at an impasse.

[adamvoss]

On this point, it would seem we are at an impasse.

I apologize for giving that impression. I thought I acknowledged that I may be wrong about Markdown, but provided reasoning (appeal to popularity) it may be a good choice. I then went on to explain the implications and options resulting from sticking to RST so you could evaluate the options and follow up as you saw fit.

Part of my explanation was to account for not knowing what you know, so protectively trying to provide information. I am assuming a lot, but from what has been said I would postulate that the difference is between more of a web-oriented (markdown) vs documentation-based background (sphinx). I thought I left the question of direction open this PR is GitHub Pages+Jekyll+Markdown and I mentioned that Travis CI+Jekyll+reStructuredText would be possible. Travis CI+Sphinx+reStructuredText sounds like it would be most familiar to you (though if you go that route ReadTheDocs+Sphinx+reStructuredText may be suitable just require more customization).