Create Dedicated Documentation Repository for ReCursor

[MasuRii]

Overview

Establish a separate repository for ReCursor's documentation website, following patterns from similar projects in the ecosystem.

Background

Based on research in research.md, several reference projects have dedicated docs sites:

Project	Docs Approach	Notes
OpenCode	Dedicated docs + README	Terminal-native, 122K stars
Claude Code	Official docs at code.claude.com	First-party, proprietary
OpenHands	ReadTheDocs	Full SDK documentation

Goals

• Improve documentation discoverability and SEO
• Enable versioned documentation tied to releases
• Support modern docs features (search, copy-as-markdown, API reference)
• Separate concerns: ReCursor repo stays focused on implementation

Research Required

Evaluate documentation frameworks:

Framework	Used By	Flutter Support	Notes
Docusaurus	Meta	External link	React-based, excellent search
VitePress	Vue ecosystem	External link	Fast, Vue-native
MkDocs Material	Python projects	External link	Markdown-first, Python toolchain
GitBook	Many startups	External link	SaaS, limited free tier

Evaluation Criteria

From CONTRIBUTING.md standards:

• Markdown-based content (portable from existing docs/)
• Responsive/mobile-friendly design (aligns with ReCursor mobile-first)
• Built-in search functionality
• Copy code / copy as markdown
• Versioning support for release docs
• GitHub Pages / CI integration (per ci-cd.md)

Proposed Repository Structure

ReCursor-Docs/
├── docs/
│   ├── getting-started/
│   ├── architecture/
│   ├── integration/
│   └── api-reference/
├── src/                    # Framework-specific files
├── static/                 # Assets, diagrams
└── docs.config.js         # Configuration

Deliverables

• Research and select documentation framework
• Create ReCursor-Docs repository under RecursiveDev org
• Migrate existing docs/ content (preserve architecture/overview.md structure)
• Set up CI/CD for automatic deployments (reference ci-cd.md patterns)
• Add cross-links between ReCursor and ReCursor-Docs READMEs

Related

• Current docs: docs/
• Research findings: research.md
• CI/CD patterns: ci-cd.md

[MasuRii]

Research Update: AI-Friendly Documentation Best Practices (2026-03-17)

This comment summarizes verified best practices for documentation sites optimized for both AI agents and human readers.

---

Key Findings

Standard	Status	Purpose	Source
llms.txt	Emerging (Sept 2024)	LLM-friendly content at well-known URL	https://llmstxt.org/
Diátaxis	Established	Systematic documentation architecture	https://diataxis.fr/
sitemap.xml	Standard	Crawler discoverability	https://www.sitemaps.org/
robots.txt	Standard	Crawler traffic management	Google Search Central
OpenAPI	Standard	Machine-readable API docs	https://spec.openapis.org/

---

1. The llms.txt Convention

What: A markdown file at /llms.txt providing LLM-optimized content navigation.

Why: LLM context windows cannot handle full HTML pages. llms.txt provides:

• Brief project background
• Guidance for LLMs on documentation usage
• Links to markdown content (stripped of nav/ads/JS)

Format Example:

# ReCursor

> Mobile-first companion UI for AI coding workflows

## Docs

- [Getting Started](/docs/getting-started.md): Quick start guide
- [Architecture](/docs/architecture.md): System design
- [API Reference](/docs/api.md): Complete API documentation

Citation: https://llmstxt.org/ (official proposal, Jeremy Howard, Sept 2024)

---

2. Diátaxis Framework

A systematic approach dividing documentation into four types:

Type	Purpose	ReCursor Example
Tutorials	Learning-oriented	"Getting Started with ReCursor"
How-to Guides	Problem-oriented	"Connect to Claude Code via Hooks"
Reference	Information-oriented	"Bridge Protocol Reference"
Explanation	Understanding-oriented	"Architecture Decision Records"

Benefits for AI discoverability:

• Predictable information hierarchy
• Clear content type signals
• Easier navigation for both humans and LLMs

Citation: https://diataxis.fr/ (official documentation)

---

3. Sitemap and Robots.txt

sitemap.xml Requirements:

• Location: /sitemap.xml
• Include canonical URLs for all pages
• Add lastmod dates for freshness signals

robots.txt Best Practices:

User-agent: *
Allow: /docs/
Disallow: /internal/
Sitemap: https://docs.recursor.dev/sitemap.xml

Citation: https://www.sitemaps.org/ (protocol specification)

---

4. Structured Navigation Elements

Element	Purpose	Implementation
Canonical URLs	Prevent duplicate content	<link rel="canonical" href="...">
Semantic headings	Content structure	Proper <h1>-<h6> hierarchy
Meta descriptions	SEO + AI context	<meta name="description">
Open Graph tags	Social + AI preview	<meta property="og:...">

---

Phased Implementation Plan

Phase	Scope	Deliverables
1. Foundation	Adopt Diátaxis structure	Reorganize existing docs/ into tutorials/how-to/reference/explanation
2. Discovery	sitemap.xml + robots.txt	Create XML sitemap, configure robots.txt
3. AI-Ready	llms.txt	Create /llms.txt with links to markdown content
4. API Docs	OpenAPI spec (future)	Machine-readable API documentation when endpoints exist
5. Deployment	CI/CD integration	Auto-generate sitemaps on publish (per docs/ci-cd.md)

---

References

1. llms.txt official: https://llmstxt.org/
2. Diátaxis framework: https://diataxis.fr/
3. Sitemap Protocol: https://www.sitemaps.org/
4. OpenAPI Specification: https://spec.openapis.org/
5. Docusaurus SEO guide: https://docusaurus.io/docs/seo
6. Full research: C:/Repository/ReCursor/docs/research/ai-friendly-docs-best-practices-2026-03-17.md