Repository navigation
Optional hierarchical documentation output and OKF-compatible export for agents #125
Description
CodeWiki produces high-quality documentation. Its coverage of business flows and implementation details is much more useful than a simple code summary.
Currently, the generated Markdown files are mostly stored in a flat directory. For large repositories, this makes it harder for an agent to navigate by business area and find the relevant documents. Would you consider an optional hierarchical output structure, with an index at each level?
Would an Open Knowledge Format (OKF)–compatible export also be worth exploring? Structured metadata such as document type, related modules, and source-code references might help agents select the right documents without loading unrelated content. The potential improvements in token usage and context quality are a hypothesis that could be evaluated against real retrieval tasks.
I’d suggest keeping the current output as the default, with hierarchical output or OKF export as optional features. Any new structure would need to keep file paths, internal links, module_tree.json, incremental updates, and the existing viewer consistent. I’d also be interested to know whether CodeWiki’s current MCP capabilities already address part of this use case.
Activity
docs: mirror the module tree in the docs folder by default
anhnh2002 commentedon Oct 2, 2026
Thanks for the detailed suggestion, and for the kind words about the docs!
Some background on why the output was flat: when we first built CodeWiki, smaller models had trouble with a nested folder layout. They kept writing wrong relative links between pages, so we kept every page in one folder. Current models handle the hierarchy well, so instead of adding hierarchy as an option, we're making it the default. #128 does this:
auth.md,auth/login.md,auth/login/tokens.md), so each parent page also works as the index for its folder.overview.mdstays at the root as the top-level index.--flatkeeps the current layout for small models.module_tree.jsonis unchanged; module names stay unique and are still the page filenames.metadata.json, and--updatekeeps it. Existing flat docs stay flat.processing_order.jsonnow gives each module'sdoc_path, so an agent driving CodeWiki through MCP writes pages in the same structure.OKF export is out of scope for this PR. The idea of letting agents pick documents by metadata (type, related modules, source references) instead of loading everything is interesting, and we'd want to measure it on real retrieval tasks, as you suggest. Let's keep it as a follow-up; if you have an OKF schema or example consumers in mind, please share them.
Feedback on #128 is welcome, especially if you try it on a large repository.