nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

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

Accepted answers

All comments

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.

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)

MCG_70eld7

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.

Janek Behrens _Janek Behrens Apps_

The bidirectional sync problem is genuinely hard, Confluence's storage format makes
clean round-trips between Confluence and Git basically impossible without a lot of pain.

One approach that sidesteps this entirely: instead of syncing Confluence pages to Git,
treat Git as the source of truth and generate Confluence pages from the code automatically.

That's what CodeDoc AI for Confluence does. You connect your repo (GitHub, GitLab,
Bitbucket, Azure DevOps), define what should be documented (API docs, architecture
overview, deployment guide, changelog...), and set a trigger — on merge, on a schedule,
or manually.

Confluence gets updated automatically. No bidirectional sync, no format conversion
headaches, no stale pages.

It won't solve the use case where you want to edit in Confluence and push back to Git —
but for the "keep Confluence in sync with what's in the repo" direction, it works well.

Marketplace: https://marketplace.atlassian.com/apps/2654352538 — happy to answer questions.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

confluence

cloud

confluence-cloud