Auto-import markdown documents as pages from git repositories

[Claudio Bantaloukas]

I just witnessed the repeated disagreement in my team between putting documentation close to the code in github and putting it on confluence where it's all centralised.

Wouldn't it be great if confluence allowed adding:

• a link to a markdown file in a git repository which is then converted into a page and kept up to date
• a link to a folder of markdown pages in a git repository, which is then converted into a tree in a space's pages section and kept up to date with changes in the repository
• and made it easy to search across all of these documents along with the confluence pages our functional and management people love so much?

CANIHAZ? :)

[John Price]

Something like this would be great, yes.  We have the same debates about choosing between git/Confluence/SharePoint and I agree with the devs that code docs should live with the code.  A better way to mirror in Confluence or link to extended docs would be great.  The only issue I see there is that our Confluence team docs are pretty wide open, but source code repos are not (usually limited to teams or business lines).  So permissioning would be interesting.  

This is what our dev tools selection guide says today:

Team Documentation 

The Dev Tools Group supports Confluence for team documentation.  It's easy to use and has excellent search, page versioning, Jira integration, and other features.  However, you are welcome to use ADOPS Wiki or GitLab Pages if those work better for your team.  

Team documentation is different from code documentation, which should live in the code repository itself.  Examples:

• Code documentation - Method and class usage details (inline), repository and service overviews, and configuration instructions (for example, README.md, CHANGELOG.md, CONTRIBUTING.md, DEVELOPMENT.md, NOTICE, CODEOWNERS, .editorconfig files), auto-generated API definitions.
• Team documentation  - Team processes and standards, feature requirements, architecture diagrams, troubleshooting/Ops guides, internal user-facing documentation.

The Confluence user documentation goes into detail about the various available Confluence instances and how to use them.

[Roman Stoffel]

We (Mibex Software) have the Include Bitbucket/GitLab/Github for Confluence apps, which may help this use case.

You can include files from the repository and render them in a Confluence page.
Markdown and AsciiDoc documents are rendered into the page by default.

There are limits:
  - Include GitLab/Github only have Cloud verision at the moment.
  - Cloud versions cannot include multiple files. You have to include it file by file.
  - Include Bitbucket for Confluence DC/Server can include multiple files via an search expression, but doesn't show those as a nice tree.

Anyway, you can try the apps out. If its close to your use case, but are missing something, let us know.

[Patrick Zivkovic]

@Claudio Bantaloukas do you have a solution to this topic? We are facing similar problems.

[Claudio Bantaloukas]

I guess I'm lucky enough to work for a company with few such barriers :)

Administrators on such companies will probably need a we-cant-have-the-good-things switch!