One of the features I always liked about github was that it rendered you README files of various formats pretty nicely when accessing the root-folder of your project. README.rst got some rst2html-love and README.md was converted from Markdown to HTML. When I first gave bitbucket a try some months ago I noticed, for the first time, how much I actually had grown to expect my READMEs to get rendered as HTML, right when I couldn’t find out how to get the same behaviour on bitbucket.
Well, there is actually a little hidden feature on the hg-hoster that lets you do the same: Simple put your markup language in an encoding-style preamble of your README-file and bitbucket will render it for you as HTML on the start-page of the source-browser::
-*- restructuredtext -*-
If you put some RestructuredText here, it will get rendered as HTML.
Thanks, jespern, for this great tip :-)
So far I’ve tried it with “restructuredtext” and “markdown” and both seem to work. There are just some things to note here:
-
This preamble gets only interpreted if it is in the very first line of your README-file.
-
That first line has to start with the preamble so currently you can’t really hide it within a comment or something like that. If you want to see this change implemented, perhaps giving this issue a little hug will help.
Do you want to give me feedback about this article in private? Please send it to comments@zerokspot.com.
Alternatively, this website also supports Webmentions. If you write a post on a blog that supports this technique, I should get notified about your link 🙂