How Graphify Generates an Agent-Crawlable Markdown Wiki

Graphify generates an agent-crawlable markdown wiki by exporting its knowledge graph as a structured collection of interlinked Markdown files, using the to_wiki function in graphify/wiki.py to create filesystem-safe slugs and relative links that AI coding assistants can navigate autonomously.

The Graphify-Labs/graphify repository transforms codebase analysis into traversable documentation. When you invoke the --wiki export flag, the tool generates a self-contained markdown wiki that serves as a machine-readable knowledge base, allowing AI agents to crawl complex code relationships without requiring interactive visualizations.

The Wiki Generation Pipeline

Triggering the Export

The wiki generation starts when users run graphify <path> --wiki from the command line. According to the source code in graphify/wiki.py, the to_wiki function orchestrates the entire export process, accepting the graph structure, community mappings, and output directory as parameters.

Pre-Processing and Validation

Before rendering content, to_wiki performs three critical housekeeping steps to ensure wiki integrity:

1. Graph Validation: The function verifies that the communities map contains data, aborting with a clear error if the graph has not been built yet.
2. Stale Node Pruning: Nodes appearing in community lists but no longer existing in the graph are removed to prevent broken links.
3. Directory Cleanup: All existing *.md files under the output directory are deleted to eliminate orphaned articles from previous runs.

Slug Resolution and Link Mapping

The wiki establishes navigability through a two-phase linking system. First, it generates slugs—filesystem-safe filenames derived from article labels using _safe_filename and made unique via _unique_slug to handle case-insensitive collisions. Then, it builds a resolver dictionary that maps each human-readable label to its corresponding slug before any article bodies are rendered. This pre-computation ensures that intra-wiki links resolve correctly throughout the entire site.

Rendering Community and God-Node Articles

The export generates two distinct article types:

Community Articles: Created by _community_article, these files contain:

• Community headers and metadata (node counts, cohesion scores)
• "Key Concepts" lists featuring the top 25 nodes by degree
• Relationship sections linking to other communities via _md_link, which emits [label](slug.md) with URL-encoded slugs
• Source file listings and audit trails showing confidence breakdowns (EXTRACTED / INFERRED / AMBIGUOUS)

God-Node Articles: Generated by _god_node_article, these dedicate pages to the most-connected concepts, listing connections grouped by relation type with confidence tags and backlinks to parent communities.

Index Generation and Output

Finally, _index_md constructs the entry point index.md, cataloging all communities and god-nodes while providing graph statistics (total nodes, edges, community count). The function writes community files, god-node files, and the index to graphify-out/wiki/, returning the total article count.

Implementation Details and Code Structure

The core implementation resides in graphify/wiki.py. The _md_link function constructs relative links using standard Markdown syntax: [{text}]({slug}.md). This approach ensures compatibility with any CommonMark renderer while maintaining filesystem portability.

The output directory structure follows this pattern:

• index.md (entry point)
• community/*.md (community documentation)
• god-node/*.md (high-connectivity concept pages)

Practical Usage Examples

Command-line invocation:

graphify ./my-project --wiki

# Writes to graphify-out/wiki/ containing index.md, community/*.md, and god-node/*.md

Direct Python API usage:

import networkx as nx
from graphify.wiki import to_wiki

G, communities, labels, god_nodes = ...   # built by Graphify

n_written = to_wiki(
    G,
    communities,
    output_dir="graphify-out/wiki",
    community_labels=labels,
    god_nodes_data=god_nodes,
)
print(f"{n_written} wiki articles generated")

Internal link generation:

# Inside _md_link(label, resolver)

# Returns a markdown link that works in any CommonMark renderer

return f"[{text}]({quote(f'{slug}.md')})"

Summary

• Graphify generates agent-crawlable wikis using the --wiki CLI flag or to_wiki() Python API
• The graphify/wiki.py module handles validation, slug generation, and Markdown rendering
• Slugs are filesystem-safe filenames that prevent collisions and encode URLs properly
• The resolver dictionary pre-maps labels to slugs before article generation to ensure valid internal links
• Output includes an index.md entry point, community articles, and god-node detail pages
• Standard Markdown with relative links enables any AI assistant (Claude Code, Codex, etc.) to crawl the knowledge base

Frequently Asked Questions

What makes the wiki "agent-crawlable"?

The wiki uses standard Markdown files with relative links (e.g., [Label](slug.md)), requiring no JavaScript or specialized rendering engines. AI coding assistants can read these files using standard filesystem tools and follow links between concepts autonomously, making the knowledge graph traversable via text-based agents.

How does Graphify prevent filename collisions when generating slugs?

The _unique_slug function in graphify/wiki.py handles case-insensitive collisions by appending numeric suffixes when labels resolve to identical filesystem names. Combined with _safe_filename, which strips unsafe characters, this ensures all generated filenames are both unique and portable across operating systems.

What distinguishes community articles from god-node articles?

Community articles (generated by _community_article) document clusters of related concepts and include metadata like node counts and cohesion scores. God-node articles (generated by _god_node_article) focus on individual high-connectivity concepts, detailing their specific relationships grouped by relation type and including confidence tags.

Where does the wiki export write its output files?

By default, the export creates a graphify-out/wiki/ directory containing index.md as the entry point, a community/ subdirectory with cluster documentation, and a god-node/ subdirectory with detailed pages for highly connected entities. This structure is created when running graphify <path> --wiki or calling to_wiki() with the default output directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}