Git Snippets for Confluence—Developer Documentation without Duplication

Ghost -

Let’s start this post with a bold claim: as software developers we like Confluence. Well, we think at least many of us do. And many of us use it as a tool to create documentation for software. In fact, we have had many projects where we started with a documentation as a simple README.md in the repository. Nowadays, Markdown allows us to write fairly extensive and nicely formatted documentation (check this one out as an example).

But that said, for almost all of these projects, the day came where we really wanted some extended functionality for these docs. What about comments on the documentation? What about sub-pages? And then after all, you don’t always want to direct potential users of your software to your repository. Of course, the repository will not always be open source and you’ll have to deal with permissions a bit more professionally.

On-the-Fly Markdown Rendering in Confluence

This is why we now integrated automatic Markdown rendering into our Confluence app Git Snippets! It’s simple: add the Git Snippets macro to a page and give it the URL to a Git or Bitbucket repository. Now, simply check the “Enable Markdown Renderer” macro parameter, and rather than rendering the raw markdown code, the macro will render the Markdown to properly formatted HTML – just like you know it from those nice Github and Bitbucket READMEs.

Wait, what’s Git Snippets for Confluence anyway?

Oh! You haven’t actually heard about our Git Snippets app yet? Git Snippets is our Git / Bitbucket integration app for Confluence. If you know our apps PocketQuery for Confluence and PocketQuery for Jira you already have an idea that we like data integration at Lively Apps. Git Snippets does something similar; just that it’s a little more targeted towards a specific use case (integrating code snippets from Github and Bitbucket). The idea is that you can create software documentation and howtos in Confluence by embedding code snippets from your repositories, rather than creating the full documentation in these repositories.

Ok, but why not use the built-in Confluence {code} macro?

The {code} macro serves a similar purpose: embed code snippets in Confluence pages. However, using the code macro, you’ll have to copy/paste the actual code inside of your page! As soon as your code changes in the repository, the code on your Confluence page will be outdated! And this is where Git Snippets really shines: your snippet will update automatically with the line range in your repository! Exactly – you change the line range in your repository, and this change will be immediately reflected on your Confluence page. Without any edits to the page! Our sweet line-range tracking algorithm makes this possible!

What’s next?

We just released Git Snippets 2.5.0 with the new Markdown Rendering feature. But 2.6.0 is already in the pipeline! We have already started to work on the new main feature which will be managing Bitbucket and Github authentication through Service Accounts. This has been a long-requested feature which will empower Bitbucket Teams and Github Orgs to leverage the potential of Git Snippets. Stay tuned!

Where to go from here?