To leverage AI Docs' automated documentation capabilities, your first step is to create a new project by connecting a GitHub repository. This process links your codebase to the AI Docs platform, initiating the AI-driven analysis and content creation pipeline.
Prerequisites
Before you can initialize your first project, ensure you have:
An AI Docs Account: You must be logged in to access the dashboard and create projects.
GitHub Repository: The URL or owner/repo identifier of the GitHub repository you wish to document.
For detailed setup instructions and system requirements, refer to Installation and Prerequisites and Environment Configuration.
Initiating Project Creation
From your Dashboard Overview, click the "Create project" button.
The "Create a new project" dialog will appear, prompting you for project details.
Providing Project Details
In the dialog, you will provide the following information:
Project Name (Optional): A human-readable name for your project (e.g., "My Awesome App"). If left blank, AI Docs will use the repository's name by default.
Repository URL (Required): The full GitHub URL of your repository (e.g., https://github.com/vercel/next.js) or the shorthand owner/repo (e.g., vercel/next.js). AI Docs validates this format to ensure it's a valid GitHub repository.
GitHub Connection and Repository Access
AI Docs integrates directly with GitHub to fetch your repository's code. The "Create a new project" dialog will display your GitHub connection status.
Public Repositories: You can connect public GitHub repositories without any additional setup.
Private Repositories: To access private repositories, you must connect your GitHub account. If not connected, an option to "Connect GitHub" will be available within the dialog. This process uses Google OAuth for user authentication, allowing AI Docs to securely access your private repositories on your behalf.
If you encounter errors like "Repository not found" or "Cannot access this repository" for a private repository, ensure your GitHub account is connected. For more details on this integration, see GitHub Integration and Authentication and User Management.
Repository Size Limits
AI Docs performs a pre-flight check to prevent processing excessively large repositories. After filtering out non-source files (like tests or configuration files), if your repository exceeds a predefined limit on the number of eligible source files, the project creation will fail. You will receive an error message indicating that the repository is too large and advising you to try a smaller one.
What Happens After Creation
When you submit the project creation form, AI Docs initiates a sophisticated backend process to set up your documentation project.
Client-Side Validation: Your browser first validates the repository URL format to catch common errors early.
API Request: A POST request is sent to the /api/projects endpoint with the project name and repository URL.
Server-Side Validation: The AI Docs server performs several critical checks:
URL Validity: It verifies that the provided URL is a valid GitHub repository URL and extracts the owner and repository name.
Project Limits: It checks your current plan to ensure you have available project slots. If you've reached your limit, you'll be prompted to upgrade. Refer to Subscription Plans and Managing Your Subscription for more details.
GitHub Access: Using your connected GitHub token (if available), AI Docs verifies that the repository exists and is accessible. If not, it will return an error, especially for private repositories where a GitHub connection is required.
Repository Size Check: To ensure efficient processing, AI Docs performs a pre-flight check of the repository's file tree. It filters out non-source files (e.g., tests, configuration files, build artifacts). If the number of eligible source files exceeds a predefined limit, the creation will fail, and you will be advised to try a smaller repository.
Project Database Entry: If all checks pass, a new project entry is created in the AI Docs database. This entry includes a unique project ID, a generated subdomain for your documentation, and a webhook secret.
GitHub Webhook Creation: AI Docs attempts to automatically create a GitHub webhook for your repository. This webhook is crucial for enabling continuous documentation updates; it triggers the documentation generation process whenever changes are pushed to your repository. This feature is typically available for higher-tier plans. See GitHub Integration and Webhooks for Automation for more details.
Ingestion Queue: A project.ingest event is sent to the Inngest queue, which orchestrates background tasks. This event initiates the asynchronous process of fetching your repository's files, analyzing the codebase, generating embeddings, and finally, creating the initial documentation. Learn more about this in How AI Docs Works and AI-Powered Generation.
Redirection: You are then redirected to your new project's dedicated dashboard page, where you can monitor its status.
Monitoring Project Status
After creating a project, you will be taken to its specific project page within the dashboard. Here, you can observe the project's status, which will typically transition through:
Pending: The project has been created and is awaiting the start of the ingestion process.
Ingesting: AI Docs is actively processing your repository, analyzing code, and generating documentation.
Ready: Documentation has been successfully generated and is available for viewing and interaction.
You can monitor the detailed progress of the ingestion pipeline under the "Activity" tab of your project dashboard. For a comprehensive guide on navigating and managing your projects, refer to Monitoring Project Activity.
Troubleshooting Common Issues
"Repository not found" or "Cannot access this repository":
Cause: The repository URL might be incorrect, or AI Docs lacks permission to access it.
Solution: Double-check the repository URL. If it's a private repository, ensure your GitHub account is connected to AI Docs via Authentication and User Management.
"Repository is too large":
Cause: The repository contains an excessive number of eligible source files, exceeding the platform's processing limits.
Solution: Consider documenting a smaller, more focused repository, or breaking down a large monorepo into smaller, independent projects.
"Project limit reached":
Cause: You have reached the maximum number of projects allowed by your current AI Docs plan.
Solution: You can delete an existing project or upgrade your subscription plan via Managing Your Subscription to increase your project limit.