DEV Community

Jean-Francis Bastien
Jean-Francis Bastien

Posted on

Docs as Code Confluence

Hi, as an introduction, I want to link a post that talked to me. How Google, Twitter, and Spotify built a culture of documentation

Since I read that article, I am looking for a way to introduce that concept to my team.

The concept and implementation are relatively easy to achieve with Github Pages, Netlify, Vercel, etc. When it comes to internal documentation, more requirements appear, for example, authorization. I also didn't want to introduce another place to look for documentation.

Since we have Confluence, the idea is to have the benefit of the concept of docs as code and keep all our documentation in the same place. Confluence will handle the "hosting", indexing and authorization.

My Workflow

GitHub logo Bhacaz / docs-as-code-confluence

Publish the content of a folder to confluence Github Action

Docs as Code - Confluence

Publish a folder of documentation to Confluence.

Create a Confluence Page for each markdown file. Each folder will create a parent page to reflect the directory structure.

Parameters

Name Description Required
folder The folder to sync true
username Confluence username or email true
password Confluence password or API token true
confluence-base-url Your Confluence URL (with wiki). Example: https://mydomain.atlassian.net/wiki true
space-key Confluence space key to publish the documentation. Located after spaces in the URL. https://mydomain.atlassian.net/wiki/spaces/<<~1234>>.
Or in Space settings > Space details > Key.
true
parent-page-id Page id under which the documentation will be published. Located after pages in the URL. https://mydomain.atlassian.net/wiki/spaces/~1234/pages/<<1234>>/My+Parent+Page true

TODO

  • Renaming a file
  • Moving/Removing a file
  • Not updating Confluence pages when there is no change
  • Add commit link to the new page version
  • Add markdown images with url source

Example of workflow

name: Sync Docs as Code -
Enter fullscreen mode Exit fullscreen mode

The action looks for a specific folder and publishes its contents to Confluence. It recreates the file structure and publishes the markdown content to a Confluence page.

Submission Category:

DIY Deployments

Yaml File or Link to Code

I create a minimal example of usage with a functional workflow, a docs folder with markdown files, and some screenshots of the result in Confluence.

Example in Confluence

Additional Resources / Info

There are still some must-have features to implement, but it's a good start for writing more technical documentation.

Top comments (0)