What options to store confluence pages in Github

[Zekai Huang]

Hi all, 

We are trying to power a confluence space with markdown files in a github repository. It requires that. 

1. The entire confluence space is powered by code in github. 

2. Any change to the selected branch in that repo results in updating confluence page. 

We try Git for Confluence, but it's mostly for embedding a file/folder into a confluence page. We found a few open source github project but all aren't maintained. We wonder if anyone has found a good way to achieve this. 

Thank you,

Zekai

[MCG]

Wanted to know if a solution was ever found to edit content in Confluence and it being available in Git.  I have a similar situation in that: 

- I'm not a developer so it would be much easier for me to edit content and if it lived Confluence

- I would really love to be able to use the Release features from Jira to publish release notes pages in Confluence and those be available in Git; in our situation the Git content is publicly available.  

This setup would allow BA/ PM to manage releases end to end rather than having to put Git into the process for BA/ PM, requiring a developer involved in the release notes, exporting/ importing content, etc, etc.

[aachrisg]

this!

I'll describe the exact usage scenario for me (except with perforce terms instead of git because that's what my industry uses):

- You're doing large scale software development with a massive codebase
- You want to write some documentation for a module of it.
- You really really want there to be a version of that documentation checked into version control in the source files directory because it solves discoverability for other programmers- they'll see it in their IDE.
- You want a common version control timeline/tree for the documentation and the code it documents, because obviously.
- You want confluence. You want to have a company-wide browseable knowledge-base, because otherwise why are you here?
-When you check in changes to the doc you want the confluence web page updated.

[Nic Brough -Adaptavist-]

Welcome to the Atlassian Community!

As mentioned in the original answer, there are some problems with this idea.

I think it might help to re-read my last comment (7/11/2023) for what you would need to be thinking about, and then I have expanded on what I said there to explain why I said it.

There's two things to think about:

• Where do you want to edit?
  • Use Confluence only, and have its versions mapped into your SCM so that it knows what version of a Confluence page to look at.
  • Use an external editor (make Confluence read-only in the spaces you need to do this in) and have the external commits flow back into Confluence.
  • Allow edits in both, which means having both translation problems below, and needing to come up with some way of mapping Confluence and SCM versions together.
• All of these run into the second problem - translations.
  • A Confluence page is not stored as plain text, or even HTML, it is stored in an SGML format (like XML or HTML).  Your external editor is not going to understand that format, so you won't be able to just "read" a page into your SCM, nor will your editor be able to write data and simply push it back into Confluence.  Your IDE is likely to have the same problem - I don't know of any IDE that can render a Confluence page from the raw code of it.
  • Your best options each way would be:
    • If using Confluence as the editor, export the page to PDF or Word (any user can do those from the UI), or use the space export (a bit more complex to code for, and only available to space admins) to get it as CSV, HTML, XML, or PDF.  
    • If using an external editor, write something that can upload the content to Confluence over the REST API, creating a new version of the page.  (The REST API does not need to be given content in Confluence format, but if you want to use the more clever stuff in Confluence, you are going to have to get your authors to write in very specific ways)

[Nic Brough -Adaptavist-]

You would need to find or write an app to do that, and you'll need to think very carefully about how can keep the two in full sync.

Conflluence already has versioning built-in, there's no need to try to wedge it into another source control system.

In the other direction, yes, yout git can create pages and update them, over the REST API, Git for Confluence, and there are a couple of other apps in the marketplace that look like they could do it.

[Garland MacNeill]

It's a lot simpler to create documentation as markdown and keep it in source control with a local copy than it is to fumble with creating a confluence page and deal with formatting. Personally I think it would be great if there was an option for Confluence to read from a repo and display the markdown from it. How hard could it be? Jekyll already does this. 

[Nic Brough -Adaptavist-]

But why?  Why are you trying to version things in two different places?

[Garland MacNeill]

I'm not. I use the repo for our depts on call docs and to create informal documentation that may change often. I would prefer if Atlassian could process that documentation like Jekyll though. 

[Nic Brough -Adaptavist-]

But you are - Confluence and git would be independently putting versions on the data.

You could automate something that would enable them to stay in sync, but you'll need to decide between:

• Not allowing edit in Confluence
• Not allowing edit in git
• Allowing both (meaning you'll need to write both solutions below)

Whatever you decide, you'll need to write some code.  One or both of something that:

• When people create, edit, or delete, a page, push the changes to git.
• When people do the same on the git side, push the new data into Confluence on commit.  (I can't recommend that - your users will need to write their pages in Confluence storage format, or the JSON the REST API understands, or you'd need to write a parser to convert what they write into a Confluence format)

I'd recommend checking out what the marketplace apps can do, rather than trying to write a sync of some sort, but a better idea might be to look at why you think you want to do this, because you probably don't.