Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Celebration

Earn badges and make progress

You're on your way to the next level! Join the Kudos program to earn points and save your progress.

Deleted user Avatar
Deleted user

Level 1: Seed

25 / 150 points

Next: Root

Avatar

1 badge earned

Collect

Participate in fun challenges

Challenges come and go, but your rewards stay with you. Do more to earn more!

Challenges
Coins

Gift kudos to your peers

What goes around comes around! Share the love by gifting kudos to your peers.

Recognition
Ribbon

Rise up in the ranks

Keep earning points to reach the top of the leaderboard. It resets every quarter so you always have a chance!

Leaderboard

Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
4,456,381
Community Members
 
Community Events
176
Community Groups

Auto-import markdown documents as pages from git repositories

Edited

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? :)

3 comments

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.

Like # people like this

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!

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

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.

Comment

Log in or Sign up to comment
TAGS

Atlassian Community Events