The official documentation website for NLWeb - a protocol that simplifies building conversational interfaces for websites and enables natural language interactions with AI agents.
This is a Next.js-based documentation website that provides comprehensive information about:
- NLWeb Protocol: A standardized interface for natural language interactions with agents
- Agent Finder: Software that helps agents discover and integrate with NLWeb-compatible websites
- Implementation Guides: Practical examples and quickstart guides
- Framework: Next.js 16.1.1 with React 19
- Documentation: MDX (Markdown + JSX) using Nextra
- Styling: Tailwind CSS 4
- UI Components: Radix UI primitives
- Syntax Highlighting: react-syntax-highlighter
- Node.js (v20 or higher recommended)
- pnpm
pnpm installRun the development server:
pnpm devOpen http://localhost:3000 to view the website.
Build the production-ready site:
pnpm buildpnpm startnlweb-internal-website/
├── app/ # Next.js app directory
│ ├── docs/ # Documentation pages
│ │ ├── intro/ # Introduction pages
│ │ ├── about/ # About and FAQ
│ │ ├── nlweb-core/ # NLWeb Core software docs
│ │ └── agent-finder/ # Agent Finder docs
│ │ ├── overview/ # Agent Finder overview
│ │ ├── motivation/ # Why Agent Finder exists
│ │ ├── quickstart/ # Getting started guide
│ │ └── api/ # API documentation
│ └── specification/ # Protocol specification
│ ├── protocol/ # Core protocol docs
│ │ ├── overview/ # Protocol overview
│ │ ├── ask/ # Ask query structure
│ │ ├── response/ # Response structure
│ │ ├── actions/ # Actions specification
│ │ └── binding/ # HTTP transport binding
│ └── appendix/ # Additional examples
│ ├── http/ # HTTP payload examples
│ └── mcp/ # MCP payload examples
├── components/ # Reusable React components
├── NLWEBSPEC.md # Source specification document
├── AGENTFINDER.md # Agent Finder design document
└── CLAUDE.md # Project instructions for Claude AI
This website uses MDX files for documentation. MDX allows you to use JSX components directly in Markdown, making it powerful for creating interactive documentation.
Routes are automatically generated from the folder structure in the app/ directory. The file system path directly maps to the URL:
app/docs/intro/page.mdx→/docs/introapp/specification/protocol/overview/page.mdx→/specification/protocol/overviewapp/docs/agent-finder/motivation/page.mdx→/docs/agent-finder/motivation
This means adding new pages is as simple as creating a new folder with a page.mdx file inside.
Documentation pages are located in the app/ directory. The file structure mirrors the URL structure:
/docs/intro→app/docs/intro/page.mdx/specification/protocol/overview→app/specification/protocol/overview/page.mdx/docs/agent-finder/motivation→app/docs/agent-finder/motivation/page.mdx
Open the relevant page.mdx file and edit it. MDX supports:
Standard Markdown:
# Heading 1
## Heading 2
### Heading 3
Regular text with **bold** and *italic*.
- Bullet points
- More points
1. Numbered lists
2. Continue...Code Blocks:
```json
{
"query": {
"text": "example"
}
}
```React Components:
<YourComponent prop="value" />Run the development server to see your changes live:
pnpm devCreate a new page.mdx file in the appropriate directory. Follow the existing structure:
app/
└── docs/
└── your-section/
└── your-page/
└── page.mdx
Start with a heading and write your content:
# Your Page Title
Your content goes here. Use Markdown syntax and JSX components as needed.
## Section 1
More content...
## Section 2
Even more content...- Navigate to the URL that matches your folder path (e.g.,
/docs/your-section/your-page) - Test internal links to and from your page
- Verify the page renders correctly with all formatting
When writing or modifying documentation, follow these conventions (based on existing pages):
- Use Clear Headings: Start with an H1 (
#) for the page title, use H2 (##) for main sections - Code Examples: Include practical code examples in appropriate language blocks
- Consistent Structure: Look at
app/specification/protocol/overview/page.mdxas a reference - Schema.org References: When applicable, reference Schema.org vocabulary
- Links: Use relative links for internal pages, absolute for external
- NLWEBSPEC.md: The authoritative NLWeb protocol specification
- AGENTFINDER.md: Design philosophy and specification for Agent Finder
- CLAUDE.md: Instructions for AI-assisted development (project guidelines)
When updating protocol documentation, consult NLWEBSPEC.md as the source of truth.
Follow the pattern in existing spec pages:
- Overview section explaining the concept
- Detailed attributes/structure definitions
- Code examples with syntax highlighting
- Cross-references to related pages
For software docs (NLWeb Core, Agent Finder):
- Overview/motivation section
- Quickstart guide with installation steps
- API reference with examples
- Use cases and best practices
Reusable components are located in the components/ directory. The site primarily uses:
- Radix UI primitives for interactive elements
- Custom components for documentation-specific needs
- React Syntax Highlighter for code blocks
When creating new pages, reuse existing components rather than creating new ones.
This site can be deployed to any platform that supports Next.js:
- Vercel: Automatic deployment with git integration
- Netlify: Similar to Vercel
- Self-hosted: Use
pnpm build && pnpm start
When contributing documentation:
- Read the source specification documents (
NLWEBSPEC.md,AGENTFINDER.md) - Follow existing page structure and styling conventions
- Create new folders and
page.mdxfiles for new pages - Test locally before submitting changes
- Ensure all internal links work correctly
Please refer to the repository license file for licensing information.
- NLWeb Protocol Spec: Documented in this site at
/specification/protocol/overview - GitHub Repository: nlweb-ai organization
- NLWeb Core: Implementation software for websites
- Agent Finder: Integration software for AI agents
For questions or issues:
- File an issue in the GitHub repository
- Check the FAQ at
/docs/about/faq - Review the specification documentation