Confluence is where many teams explain how their systems work. It holds the deployment runbooks, architecture decisions, onboarding guides, and practical details that give code its context.
That knowledge becomes more useful when it can travel. An engineer may want to read a runbook alongside a repository. A search tool may need to index it. An AI assistant may need the explanation behind a technical decision before suggesting a change.
The Open Knowledge Format (OKF) provides a shared way to represent that knowledge. Conf2Git uses OKF as its export format to bring Confluence content into GitHub, connecting the place where teams write with the tools that can put their knowledge to work.
What is OKF?
OKF is an open specification for packaging knowledge as Markdown files with YAML frontmatter: a small metadata block at the beginning of a document. The body holds the readable content; the metadata describes it.
In the current v0.2 specification, type is the only frontmatter field always required for a concept document. Optional fields can describe sources, verification, and freshness. Ordinary Markdown links connect related concepts. See the official OKF specification.
Why a shared format matters
A collection of files becomes easier to reuse when producers and consumers agree on its conventions. Without that agreement, every export pipeline and downstream tool has to decide for itself how to describe documents, identify sources, and interpret relationships.
OKF gives them a common starting point. Its design combines readable text, structured metadata, and links in a format that can move between systems. Google's OKF project overview describes several practical benefits:
- People can inspect the knowledge directly. A text editor is enough to read the underlying files.
- Git can track changes. Teams can compare revisions and inspect the history of the exported content.
- Tools can use metadata. Fields such as document type and tags provide useful inputs for filtering and indexing.
- The files remain portable. A knowledge bundle can move as a directory, repository, or archive.
For a team choosing how to manage its documentation, that portability has a lasting benefit: the work invested in writing useful explanations can remain valuable as its tools change.
Why this matters for AI
AI tools need context about the organization they are helping. A model may understand a programming language yet have no knowledge of your deployment rules, internal terminology, or reasons for choosing a particular architecture.
Google Cloud introduced OKF to help make that surrounding knowledge exchangeable between producers and consumers. Its announcement describes a format intended for both people and agents, independent of a particular model or framework.
Our view is that a shared format lowers the effort of preparing knowledge for future uses. A team can maintain useful documentation today while leaving more options open for search, retrieval, and AI workflows tomorrow. Each consuming tool still needs a way to access and process the files; choosing OKF alone does not connect an assistant to your repository or guarantee the quality of its answers.
How Conf2Git puts OKF to work
Conf2Git brings this approach to teams writing in Confluence. Its native export implementation uses OKF v0.2, with GitHub as the destination for the generated knowledge mirror. OKF is built into the conversion pipeline, so the output does not need a separate post-export transformation.
The direction is straightforward:
Confluence → Conf2Git → OKF in GitHub
Confluence remains the source of truth. Conf2Git reads the source content, converts it to Markdown, and publishes the generated mirror to a dedicated GitHub branch that is separate from the repository's default branch. The Conf2Git setup guide explains how to configure and verify that first synchronization.
The product also handles practical details that matter when a collection of pages becomes a repository. Supported links between exported pages become relative links. Referenced, supported images are mirrored alongside their pages. Moves and renames update affected paths and internal links together. See the conversion guide for the supported content and its limits.
What travels with an exported page?
The native exporter writes each Confluence page as a page.md concept inside a directory that includes its readable title slug and stable page ID. A hypothetical deployment guide might appear at confluence/engineering--777/deployment-guide--123456/page.md.
Each concept carries its title and canonical Confluence URL. A matching sources entry identifies the source page and includes its modification time when that information is known. The generated.by field identifies the Conf2Git converter that produced the output.
For example, these selected fields illustrate the emitted metadata using synthetic page details; the full export also contains a conf2git metadata block:
okf_version: "0.2"
type: "Confluence Page"
title: "Deployment guide"
resource: "https://example.atlassian.net/wiki/spaces/ENG/pages/123456"
sources:
- resource: "https://example.atlassian.net/wiki/spaces/ENG/pages/123456"
title: "Deployment guide"
generated:
by: "conf2git/2.0.0"The conf2git block preserves application details such as source page and space identifiers, source version, and a hash of the normalized Markdown body. Standard OKF fields give other tools a familiar way to read the document, while the application fields retain details specific to the mirror.
The exporter keeps this metadata grounded in what it knows. It does not invent a human verification, expiry date, or review status for a page. It also avoids adding a new export timestamp on every run: unchanged content should produce stable output. Provenance helps a reader find and assess the source; exporting a page does not certify that its instructions are correct.
What that means for an everyday workflow
Imagine an engineering team maintaining a deployment guide in Confluence. Its authors continue updating the guide there. After a successful Conf2Git sync, engineers can inspect the generated version in GitHub and compare it with earlier exported revisions.
The team could then build a separate workflow that indexes those files or makes them available to an approved AI tool. This is an example of how the exported knowledge could be reused; it does not imply that Conf2Git supplies an indexing service or an AI integration.
Treat the mirror as generated output. Changes belong in Confluence: a later synchronization may replace edits made directly to managed GitHub files. The managed-file guide explains that boundary.
Keep the right expectations
An open export format makes knowledge easier to move, but the export still has a defined scope. Conf2Git provides a one-way mirror. It does not send GitHub edits back to Confluence or preserve every Confluence feature as a complete backup. Review its backup limitations before relying on the mirror for continuity planning.
Access also needs deliberate configuration. Confluence page permissions are not reproduced in GitHub; the destination repository controls access to the exported files. The Conf2Git FAQ explains this distinction.
Give your documentation more places to be useful
OKF offers a practical foundation for knowledge that people and tools can share. Conf2Git applies that idea to Confluence, bringing documentation into GitHub while keeping authorship in the team's existing workflow.
Explore Conf2Git or follow the getting-started guide to learn how the mirror works.