adk-ts/apps/docs

ADK-TS Documentation Site

Contributing guide for the official ADK-TS documentation
Setup • Development • Contributing • Best practices

---

📖 About

This README is specifically for contributors to the ADK-TS documentation. The documentation site is built with Next.js and Fumadocs, providing comprehensive guides, API references, tutorials, and examples for building AI agents in TypeScript with ADK-TS.

If you're looking to use ADK-TS, visit the live documentation. This guide is for those who want to contribute to improving the documentation.

🚀 Getting Started

Prerequisites

Before contributing to the documentation, ensure you have:

• Node.js (version 18 or later)
• pnpm (recommended package manager)
• Basic familiarity with Markdown and MDX

Setting Up Development Environment

1. Clone the repository (if you haven't already):

   git clone https://github.com/IQAIcom/adk-ts.git
   cd adk-ts
   

2. Install dependencies:

   pnpm install
   

3. Navigate to the docs directory:

   cd apps/docs
   

4. Start the development server:

   pnpm dev
   

5. View the documentation at http://localhost:3000

The development server supports hot reloading, so changes to documentation files will be reflected immediately in your browser.

Building for Production

Test your changes by building the documentation:

pnpm build

To run the production build locally:

pnpm start

⚙️ Architecture Overview

The documentation site uses:

• Next.js 15 - React framework with App Router
• Fumadocs - Documentation-focused React components and utilities
• Tailwind CSS - Utility-first CSS framework
• Lucide React - Icon library
• next-themes - Theme switching
• PostHog - Analytics (production only)

🤝 How to Contribute

Content Structure

All documentation content is written in MDX format and organized in the content/docs/ directory:

• framework/ - Core ADK-TS framework documentation
• cli/ - ADK-TS CLI documentation
• mcp-servers/ - Model Context Protocol server documentation

Types of Documentation Contributions

We welcome various types of contributions to improve the documentation:

• Fix typos and grammar - Help improve readability
• Add missing examples - Provide code samples for complex concepts
• Improve explanations - Make difficult topics easier to understand
• Add new sections - Cover missing topics or use cases
• Update outdated content - Keep documentation current with latest features
• Improve navigation - Enhance the organization and discoverability

Writing Guidelines

1. Use clear, concise language - Write for developers of all skill levels
2. Include code examples - Provide working code snippets whenever possible
3. Follow MDX syntax - Use proper frontmatter and MDX components
4. Add metadata - Include proper title, description, and navigation order in frontmatter
5. Use headings appropriately - Structure content with H1, H2, H3, etc.
6. Call out important information - Use callouts for tips, warnings, and important notes

Contribution Workflow

1. Fork the repository on GitHub

2. Create a feature branch from main:

   git checkout -b docs/improve-agent-examples
   

3. Make your changes following the writing guidelines above

4. Test locally with pnpm dev to ensure everything works

5. Commit your changes with descriptive commit messages:

   git commit -m "docs: add examples for custom tool creation"
   

6. Push to your fork and create a Pull Request

Getting Help

• Check existing issues for similar questions or problems
• Ask in discussions for clarification on documentation topics

For more detailed contribution guidelines, see the main project's Contributing Guide.

📚 Resources for Contributors

Documentation Tools & Frameworks

• Fumadocs - Documentation framework powering this site
• MDX - Markdown with JSX components
• Next.js - React framework for the documentation site

ADK-TS Framework Resources

• ADK-TS Repository - Main framework repository
• Live Documentation - Published documentation site
• Contributing Guide - General project contribution guidelines
• Examples - Code examples and tutorials

Writing & Style Resources

• Markdown Guide - Comprehensive Markdown reference
• MDX Documentation - Learn about MDX syntax and components
• Fumadocs Components - Available UI components for documentation

---

Ready to contribute? Start by exploring the content/docs/ directory and improving existing pages or adding new content. Your contributions help make ADK-TS more accessible and useful for developers worldwide!