https://github.com/catuscio/wiki-as-readme
Turn your codebase into a comprehensive Wiki in minutes, delivered in a single Readme. Works with Any Model. Any Repo. Any Environment.
https://github.com/catuscio/wiki-as-readme
ai-tools documentation documentation-generator documentation-tool fastapi github-actions knowledge-base litellm mermaid readme streamlit wiki
Last synced: 4 months ago
JSON representation
Turn your codebase into a comprehensive Wiki in minutes, delivered in a single Readme. Works with Any Model. Any Repo. Any Environment.
- Host: GitHub
- URL: https://github.com/catuscio/wiki-as-readme
- Owner: catuscio
- License: mit
- Created: 2026-01-01T15:20:19.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-09T16:17:33.000Z (5 months ago)
- Last Synced: 2026-01-13T21:30:45.661Z (5 months ago)
- Topics: ai-tools, documentation, documentation-generator, documentation-tool, fastapi, github-actions, knowledge-base, litellm, mermaid, readme, streamlit, wiki
- Language: Python
- Homepage:
- Size: 5.89 MB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
- Notice: NOTICE.md
Awesome Lists containing this project
README
# 📚 Wiki As Readme
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://streamlit.io)
[](https://fastapi.tiangolo.com)
[](https://docs.litellm.ai/)
> **Turn your codebase into a comprehensive Wiki in minutes.**
>
> **Any Model. Any Repo. Any Environment.**
**Wiki As Readme** is the most flexible AI documentation tool available. Whether you're running a local Llama 3 model via Ollama, using Google's Gemini Pro, or hitting OpenAI's API, this tool adapts to your stack. It seamlessly integrates with any Git platform (GitHub, GitLab, Bitbucket) or local folders, making it the ultimate "drop-in" documentation solution.
> [!NOTE]
> Some features and integrations are currently under development. **Wiki-As-Readme** warmly welcomes your contributions and Pull Requests!
## ✨ Universal Compatibility
This project is built to be **truly pluggable**. You choose how to run it, where to run it, and what powers it.
### 🧠 1. Model Agnostic (Powered by LiteLLM)
* **Commercial APIs:** Google Vertex AI (Gemini), OpenAI (GPT-4), Anthropic (Claude), xAI (Grok).
* **Open/Local Models:** **Ollama**, OpenRouter, HuggingFace.
* **On-Premise:** Connect to your own private LLM endpoints safely.
### 🚉 2. Platform Agnostic
* **Cloud Repos:** Works seamlessly with **GitHub**, **GitLab**, and **Bitbucket**.
* **Local Development:** Analyze code directly from your local file system without pushing.
* **Private/Enterprise:** Full support for private instances and self-hosted Git servers.
### 🛠️ 3. Deployment Agnostic
* **CI/CD:** Drop it into GitHub Actions.
* **Container:** Run it via Docker Compose.
* **Service:** Deploy as a long-running API server with Webhooks.
* **CLI:** Run it locally while you code.
## ⚡ Core Features
**🧠 Deep Context Analysis:**\
Analyzes file structure and relationships to understand the project's architecture before writing.
**📦 Smart Structure Generation:**\
Automatically determines a logical hierarchy (Sections > Pages) for your documentation.
**🔍 Comprehensive Content:**\
Writes detailed pages including architecture overviews, installation guides, and API references.
**📊 Automatic Diagrams:**\
Generates **Mermaid.js** diagrams (Flowcharts, Sequence diagrams, Class diagrams) to visualize architecture.
**🚗 Hybrid Output:**\
Generates both individual Markdown files for a Wiki and a single consolidated `README.md`.
**⚡ Async & Scalable:**\
Built with **FastAPI** and **AsyncIO** for non-blocking, efficient generation of large documentations.
## 📖 Examples
Curious about the results? Check out our sample outputs to see the quality of documentation generated by **Wiki As Readme**:
**[LangGraph Wiki Example (English)](examples/langgraph_readme_en.md)**
- A high-quality, structured wiki generated from the [LangGraph](https://github.com/langchain-ai/langgraph) repository, featuring architecture overviews, core concepts, and Mermaid diagrams.
**[LangGraph Wiki Example (Korean)](examples/langgraph_readme_ko.md)**
- The same LangGraph wiki, but generated in Korean.
**[Wiki As Readme's Own Wiki](examples/wiki_as_README.md)**
- Documentation for this project, generated by itself!
**[Notion Sync Example (Live)](https://welcometogyuminworld.notion.site/Wiki-As-Readme-2e2b152141a48042837dcd05a9244b7a?source=copy_link)**
- See how the generated wiki is automatically organized into a Notion database with sub-pages and structured content.
## 🚀 Usage Modes
This project is designed to be **pluggable** and can be used in multiple ways depending on your needs:
1. **[GitHub Action](#1-github-action-recommended)**
- Automate documentation updates in your CI/CD pipeline.
2. **[Docker Compose (Local)](#2-docker-compose-local)**
- Run the full UI/API locally without installing Python dependencies.
3. **[Local Python Development](#3-local-python-development)**
- For developers who want to modify the source code.
4. **[Server & Webhooks](#4-server--webhooks)**
- Deploy as a long-running service with Webhook support.
---
### 1. GitHub Action (Recommended)
Add this workflow to your repository to automatically update a `WIKI.md` file whenever you push changes.
**🎮 Manual Trigger:**\
You can manually run the workflow from the "Actions" tab and customize settings (Language, Model, Notion Sync, Commit Method) on the fly.
**📒 Notion Sync:**\
Optionally sync the generated content to a Notion Database.
1. Create `.github/workflows/update-wiki.yml`:
```yaml
name: Wiki-As-Readme As Action
on:
# 1. When pushing to main branch (runs automatically with defaults)
push:
branches:
- main
paths-ignore:
- 'README.md'
- 'WIKI.md'
- '.github/workflows/update-wiki.yml'
# 2. Manual trigger (allows custom input settings)
# "Use workflow from" menu in GitHub UI handles branch selection automatically.
workflow_dispatch:
inputs:
language:
description: 'Language code (e.g., ko, en, ja, etc.)'
required: false
default: 'en'
llm_provider:
description: 'LLM Provider (google, openai, anthropic, etc.)'
required: false
default: 'google'
model_name:
description: 'Model Name'
required: false
default: 'gemini-2.5-flash'
sync_to_notion:
description: 'Sync to Notion? (true/false)'
type: boolean
required: false
default: false
commit_method:
description: 'How to apply changes'
type: choice
options:
- push
- pull-request
default: 'push'
jobs:
wiki-time:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
env:
WIKI_OUTPUT_PATH: "WIKI.md"
steps:
# 1. Checkout code
# No 'ref' needed; it automatically checks out the branch selected in the "Run workflow" UI.
- name: Checkout code
uses: actions/checkout@v4
# -----------------------------------------------------------------------
# [OPTIONAL] GCP Credentials Setup
# Create GCP key only if using Google Provider (defaults to 'google' if undefined)
# -----------------------------------------------------------------------
- name: Create GCP Credentials File
if: ${{ (inputs.llm_provider == 'google') || (inputs.llm_provider == '') || (github.event_name == 'push') }}
env:
GCP_KEY: ${{ secrets.GOOGLE_APPLICATION_CREDENTIALS }}
run: |
if [ -n "$GCP_KEY" ]; then
echo "$GCP_KEY" > ./gcp-key.json
else
echo "::warning::GOOGLE_APPLICATION_CREDENTIALS secret is missing, but provider is set to google."
fi
# 2. Generate Wiki Content & Sync
- name: Generate Content (and Sync to Notion if enabled)
uses: docker://ghcr.io/catuscio/wiki-as-readme-action:latest
env:
# --- Basic Settings ---
# Use input if available, otherwise default to 'en' (e.g., for push events)
LANGUAGE: ${{ inputs.language || 'en' }}
WIKI_OUTPUT_PATH: ${{ env.WIKI_OUTPUT_PATH }}
# --- LLM Provider and Model Settings ---
LLM_PROVIDER: ${{ inputs.llm_provider || 'google' }}
MODEL_NAME: ${{ inputs.model_name || 'gemini-2.5-flash' }}
# --- API Key Settings ---
# [GCP / Vertex AI]
GCP_PROJECT_NAME: ${{ secrets.GCP_PROJECT_NAME }}
GCP_MODEL_LOCATION: ${{ secrets.GCP_MODEL_LOCATION }}
GOOGLE_APPLICATION_CREDENTIALS: /github/workspace/gcp-key.json
# [Other Providers]
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# --- GitHub Token ---
GIT_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# --- Notion Sync Settings ---
# Pass "true" only if inputs.sync_to_notion is true; otherwise "false" (including push events)
NOTION_SYNC_ENABLED: ${{ inputs.sync_to_notion || 'false' }}
NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
NOTION_DATABASE_ID: ${{ secrets.NOTION_DATABASE_ID }}
# -----------------------------------------------------------------------
# [OPTIONAL] GCP Credentials Cleanup
# -----------------------------------------------------------------------
- name: Remove GCP Credentials File
if: always()
run: rm -f ./gcp-key.json
# 3. Commit and Push Changes (Update file in GitHub Repo)
# Option A: Direct Push (default for push events or when 'push' is selected)
- name: Commit and Push changes
if: ${{ inputs.commit_method == 'push' || github.event_name == 'push' }}
uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "✨📚 Update ${{ env.WIKI_OUTPUT_PATH }} via Wiki-As-Readme Action (${{ inputs.language || 'en' }})"
file_pattern: ${{ env.WIKI_OUTPUT_PATH }}
# Option B: Create Pull Request (when 'pull-request' is selected)
- name: Create Pull Request
if: ${{ inputs.commit_method == 'pull-request' }}
uses: peter-evans/create-pull-request@v7
with:
title: "✨📚 Update ${{ env.WIKI_OUTPUT_PATH }} via Wiki-As-Readme Action"
body: |
This PR was automatically generated by [Wiki-As-Readme](https://github.com/catuscio/wiki-as-readme) Action.
It includes the following changes:
- Updated wiki content in **${{ env.WIKI_OUTPUT_PATH }}** based on the current state of the repository.
- (If enabled) Synchronized changes to the linked Notion database.
---
> 📖 Powered by [Wiki-As-Readme](https://github.com/catuscio/wiki-as-readme)
> Turn your codebase into a comprehensive Wiki in minutes, delivered in a single Readme.
> Works with Any Model. Any Repo. Any Environment.
branch: wiki-update-${{ github.run_id }}
commit-message: "✨📚 Update ${{ env.WIKI_OUTPUT_PATH }} via Wiki-As-Readme Action (${{ inputs.language || 'en' }})"
add-paths: ${{ env.WIKI_OUTPUT_PATH }}
```
#### How it triggers
The workflow runs in two ways:
| Trigger | When | Commit Method | Settings |
| :--- | :--- | :--- | :--- |
| **`push`** | Code is pushed to `main` | Always **Direct Push** | Uses defaults (language: `en`, model: `gemini-2.5-flash`) |
| **`workflow_dispatch`** | Manually from the "Actions" tab | Choose **Push** or **Pull Request** | Customizable per run |
> Changes to `README.md`, `WIKI.md`, and the workflow file itself are excluded from push triggers via `paths-ignore` to prevent infinite loops.
#### Commit Method: Direct Push (default)
When `commit_method` is `push` (or on automatic `push` events):
1. The generated `WIKI.md` is committed directly to the current branch.
2. Uses [`stefanzweifel/git-auto-commit-action`](https://github.com/stefanzweifel/git-auto-commit-action) to detect changes, stage `WIKI.md`, and push.
3. If the content hasn't changed, no commit is created.
4. The commit message follows the format: `✨📚 Update WIKI.md via Wiki-As-Readme Action (en)`
Best for: **Automated workflows** where you want docs to always stay in sync with the code.
#### Commit Method: Pull Request
When `commit_method` is `pull-request` (only available via manual trigger):
1. A new branch `wiki-update-{run_id}` is created from the current branch.
2. The generated `WIKI.md` is committed to that branch.
3. A Pull Request is automatically opened against the current branch using [`peter-evans/create-pull-request`](https://github.com/peter-evans/create-pull-request).
4. The PR body includes a summary of what was generated and links back to Wiki-As-Readme.
Best for:
- **Team workflows** where wiki changes should be reviewed before merging.
- **CI/CD environments** where pushes to `main`/`develop` trigger deployments — using a PR avoids accidentally kicking off a deploy pipeline from an auto-generated doc commit.
#### Required Secrets
| Secret | Required | Description |
| :--- | :--- | :--- |
| `GOOGLE_APPLICATION_CREDENTIALS` | If using Google/Vertex AI | GCP service account JSON key |
| `GCP_PROJECT_NAME` | If using Google/Vertex AI | Vertex AI project ID |
| `GCP_MODEL_LOCATION` | If using Google/Vertex AI | Vertex AI region |
| `OPENAI_API_KEY` | If using OpenAI | OpenAI API key |
| `ANTHROPIC_API_KEY` | If using Anthropic | Anthropic API key |
| `NOTION_API_KEY` | If Notion sync enabled | Notion integration token |
| `NOTION_DATABASE_ID` | If Notion sync enabled | Target Notion database ID |
> `GITHUB_TOKEN` is automatically provided by GitHub Actions — no manual setup needed. It requires `contents: write` and `pull-requests: write` permissions as configured in the workflow.
### 2. Docker Compose (Local)
Run the application locally with a single command. This is the easiest way to try out the UI.
1. **Configure `.env`**:
Copy `.env.example` to `.env`.
- Set your API keys (e.g., `LLM_PROVIDER`, `OPENAI_API_KEY`, or `GCP_...`).
- (Optional) Configure Notion Sync settings (`NOTION_SYNC_ENABLED`, etc.) or change the `LOCAL_REPO_PATH` to point to your target code.
2. **Run**:
```bash
docker-compose up --build
```
3. **Access**:
- **Web UI**: `http://localhost:8501`
- _Tip: Use the **History** tab in the sidebar to view and download previously generated wikis._
- **API Docs**: `http://localhost:8000/docs`
### 3. Local Python Development
For developers who want to modify the source code or run without Docker.
**Prerequisites:** Python 3.12+, [uv](https://github.com/astral-sh/uv).
1. **Clone & Install**:
```bash
git clone https://github.com/catuscio/wiki-as-readme.git
cd wiki-as-readme
uv sync
source .venv/bin/activate
```
2. **Configure `.env`**:
Copy `.env.example` to `.env` and set your variables.
3. **Run Backend**:
```bash
uv run uvicorn src.server:app --reload --port 8000
```
4. **Run Frontend**:
```bash
uv run streamlit run src/app.py
```
### 4. Server & Webhooks
You can deploy the API server to handle requests or webhooks (e.g., from GitHub).
- **Endpoint**: `POST /api/v1/webhook/github`
- **Payload**: Standard GitHub push event payload.
- **Behavior**: Triggers a background task to generate the wiki for the repository and commit it back (requires `GIT_API_TOKEN`).
### Configuration Reference (`.env`)
Whether running locally or in Docker, you configure the app via environment variables.
See [`.env.example`](.env.example) for a complete template with comments.
| Category | Variable | Description | Default |
| :--- | :--- | :--- | :--- |
| **LLM** | `LLM_PROVIDER` | `google`, `openai`, `anthropic`, `xai`, `openrouter`, `ollama` | `google` |
| | `MODEL_NAME` | Specific model identifier | `gemini-2.5-flash` |
| | `LLM_BASE_URL` | Custom base URL (e.g., for Ollama or proxies) | — |
| | `USE_STRUCTURED_OUTPUT`| Use native JSON mode (requires model support) | `true` |
| | `temperature` | LLM randomness (0.0 = deterministic, 1.0 = creative) | `0.0` |
| | `max_retries` | Retry count for failed LLM requests | `3` |
| | `max_concurrency` | Max parallel LLM calls (prevents rate limits) | `5` |
| **Auth** | `OPENAI_API_KEY` | OpenAI API Key | — |
| | `ANTHROPIC_API_KEY` | Anthropic API Key | — |
| | `OPENROUTER_API_KEY` | OpenRouter API Key | — |
| | `XAI_API_KEY` | xAI API Key | — |
| | `GIT_API_TOKEN` | GitHub/GitLab PAT for private repos | — |
| **GCP** | `GCP_PROJECT_NAME` | Vertex AI Project ID | — |
| | `GCP_MODEL_LOCATION` | Vertex AI Region | — |
| **Output** | `language` | Wiki language (`ko`, `en`, `ja`, `zh`, `zh-tw`, `es`, `vi`, `pt-br`, `fr`, `ru`) | `en` |
| | `WIKI_OUTPUT_PATH` | Path to save generated wiki | `./WIKI.md` |
| | `LOCAL_REPO_PATH` | Local repo path for Docker mounting | `.` |
| | `IGNORED_PATTERNS` | **JSON array** of glob patterns to exclude from analysis | (see `config.py`) |
| **Notion** | `NOTION_SYNC_ENABLED` | Sync to Notion after generation | `false` |
| | `NOTION_API_KEY` | Notion Integration Token | — |
| | `NOTION_DATABASE_ID` | Target Notion Database ID | — |
| **Webhook** | `GITHUB_WEBHOOK_SECRET`| HMAC secret for webhook signature verification | — |
## 🔌 API Reference
The backend API is built with FastAPI. You can access the interactive Swagger documentation at `http://localhost:8000/docs` when the server is running.
### Wiki Generation
#### `POST /api/v1/wiki/generate/file`
Starts a background task to generate the wiki and saves it as a Markdown file on the server.
**Request Body:**
```json
{
"repo_url": "https://github.com/owner/repo",
"repo_type": "github",
"language": "en",
"is_comprehensive_view": true
}
```
#### `POST /api/v1/wiki/generate/text`
Starts a background task to generate the wiki. The resulting text is stored in the task status.
#### `GET /api/v1/wiki/status/{task_id}`
Retrieves the status and result of a generation task.
### Webhooks
#### `POST /api/v1/webhook/github`
Endpoint for GitHub Webhooks (Push events). Triggers automatic wiki generation on pushes to the `main` branch.
- **HMAC Verification:** If `GITHUB_WEBHOOK_SECRET` is set, the endpoint verifies the `X-Hub-Signature-256` header.
- **Loop Prevention:** Commits made by `Wiki-As-Readme-Bot` or containing "via Wiki-As-Readme" in the message are automatically ignored to prevent infinite loops.
- **Branch Filter:** Only `refs/heads/main` pushes trigger generation; all other branches are ignored.
- **Requires:** `GITHUB_ACCESS_TOKEN` environment variable to commit the generated wiki back to the repository.
## 🛠️ Architecture
* **Frontend:** [Streamlit](https://streamlit.io/) (User Interface)
* **Backend:** [FastAPI](https://fastapi.tiangolo.com/) (REST API, Background Tasks)
* **LLM Integration:** [LiteLLM](https://docs.litellm.ai/) (Unified interface for 100+ LLMs)
* **Data Models:** [Pydantic](https://docs.pydantic.dev/) (Type safety & Structured Output validation)
* **Diagrams:** Mermaid.js
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the project.
2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
4. Push to the branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-----
### Acknowledgments
* This project is heavily influenced by and utilizes core logic from [deepwiki-open](https://github.com/AsyncFuncAI/deepwiki-open) by AsyncFuncAI.
* Built with the power of open-source libraries.
* Inspired by the need for better automated documentation.