Serve "project pages" from /docs folder without a plugin?

Graham Hannington December 5, 2017

My employer uses Bitbucket Server to host Git repositories on the company intranet.

I have a repo that I want to publish on GitHub. Yes, sorry: specifically GitHub, not any other repo host.

I have written the repo user documentation in (X)HTML, with associated CSS and JavaScript. I can use Markdown and templates, but my background is in SGML/XML authoring and development; I would crawl over ten flavors of Markdown to get to one XML vocabulary. The user documentation involves <iframe> HTML elements, which is one reason I want to separate it from the Markdown-source repo readme.

(Aside: I wish I could apply inline code formatting to Atlassian Community questions! The Details toolbar offers bold, italic, and underline, but not code. The Formats dropdown offers code blocks, but I want inline code phrases.)

GitHub has a feature called "Project Pages": I can add my HTML files to the /docs folder of the master branch (or to a separate gh-pages branch), and GitHub will serve them "as-is", as opposed to treating them as source to be displayed wrapped in GitHub's chrome.

I want to host my repo internally on Bitbucket Server, and preview the docs (in the /docs folder) as they will appear on GitHub.

Unfortunately, it seems Bitbucket Server does not natively offer this feature. (I'm aware of Bitbucket Server issue BSERV-4099.) I need a plugin, such as the for-money Pages for Bitbucket Server. That's not an option for me in the short term.

So, instead, I'll have to "preview" the docs by serving the /docs folder from a repo clone, using my own HTTP server. It's not a huge deal, just an annoyance.

I wish a GitHub-like "Project Pages" feature was baked into Bitbucket Server.

More generally, I wish for greater parity between Bitbucket Server and GitHub; I've also been caught out by differences in Markdown support and rendering in the readme.

Am I overlooking an easy way to get this "Project Pages" feature in Bitbucket? I confess I haven't yet looked into how much work it would be to write my own plugin to serve /docs "as-is". If I get time, I'll look into it.

0 answers

Suggest an answer

Log in or Sign up to answer
TAGS
AUG Leaders

Atlassian Community Events