For software engineering teams, documentation has always been a tug-of-war πͺ’. Developers want to write documentation in their IDEs π» using Markdown, keeping it right next to the code it describes. Product managers, stakeholders, and support teams want that same documentation in a centralized, searchable knowledge base like Confluence π.
The traditional result? Copied-and-pasted text π, stale Wiki pages πΈοΈ, and documentation that falls out of sync the moment a new feature is deployed π.
OpenWiki is the missing link π that solves this by fully embracing the “Docs-as-Code” philosophy β¨.
π οΈ What is OpenWiki?
At its core, OpenWiki isn’t a complex standalone software platform; it is a structural pattern and a pipeline methodology ποΈ. It involves dedicating an openwiki/ directory inside your standard application repository π.
Developers write standard Markdown files alongside their source code. Because the docs live in the repository:
- ποΈ They are version-controlled by Git.
- π They go through standard Pull Request (PR) reviews.
- π They branch and merge exactly when the features they describe branch and merge.
π€ Automating the Sync (The Pipeline Integration)
The magic happens πͺ when OpenWiki is integrated into a CI/CD pipeline (like Google Cloud Build, GitHub Actions, or Jenkins βοΈ). Instead of asking developers to manually copy their Markdown files over to Confluence, the pipeline handles it automatically on every merge to master π’.
Here is how a standard OpenWiki integration flows:
1οΈβ£ The Trigger: A developer merges a PR containing code updates and modifications to the openwiki/ Markdown files.
2οΈβ£ The Pre-Processor: The pipeline spins up and runs a sanitation script π§Ή (like prepare_openwiki.py). This script normalizes standard Markdown, converts complex Mermaid.js diagrams π§ββοΈ into Atlassian-friendly macros, and ensures page titles won’t conflict with existing pages.
3οΈβ£ The Publisher: A tool like md2conf authenticates with the Confluence API π, translates the Markdown into Confluence Storage Format (CSF), and publishes the pages to a designated Space π.
The result is a single source of truth π―: Developers never have to leave their terminals π¨βπ», and the business always has perfectly formatted, up-to-date documentation in Confluence π.
You can explore the code, pipeline configurations, and pre-processor scripts directly in the (OpenWiki GitHub Repository)[https://github.com/langchain-ai/openwiki].
