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
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-id |
Confluence space id to publish the documentation. Located after spaces in the URL. https://mydomain.atlassian.net/wiki/spaces/<<~1234>>
|
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
Example of workflow
name: Sync Docs as Code - Confluence
on
push:
branches:
- main
paths:
- 'docs/**'
jobs:
…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.
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)