Promote Sign in Sign up

Repository

website

NLWeb.ai website

nlweb-ai
Repository

README

NLWeb.ai Website

The official documentation website for NLWeb - a protocol that simplifies building conversational interfaces for websites and enables natural language interactions with AI agents.

Overview

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

Tech Stack

  • 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

Getting Started

Prerequisites

  • Node.js (v20 or higher recommended)
  • pnpm

Installation

pnpm install

Development

Run the development server:

pnpm dev

Open http://localhost:3000 to view the website.

Build

Build the production-ready site:

pnpm build

Start Production Server

pnpm start

Project Structure

nlweb-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

Documentation

How Documentation Works

This website uses MDX files for documentation. MDX allows you to use JSX components directly in Markdown, making it powerful for creating interactive documentation.

Route Structure

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/intro
  • app/specification/protocol/overview/page.mdx → /specification/protocol/overview
  • app/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.

Modifying Existing Documentation

1. Find the MDX File

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

2. Edit the MDX File

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" />

3. Test Your Changes

Run the development server to see your changes live:

pnpm dev

Adding New Documentation Pages

1. Create the MDX File

Create a new page.mdx file in the appropriate directory. Follow the existing structure:

app/
  └── docs/
      └── your-section/
          └── your-page/
              └── page.mdx

2. Add Content

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...

3. Verify Your Page

  • 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

Documentation Style Guidelines

When writing or modifying documentation, follow these conventions (based on existing pages):

  1. Use Clear Headings: Start with an H1 (#) for the page title, use H2 (##) for main sections
  2. Code Examples: Include practical code examples in appropriate language blocks
  3. Consistent Structure: Look at app/specification/protocol/overview/page.mdx as a reference
  4. Schema.org References: When applicable, reference Schema.org vocabulary
  5. Links: Use relative links for internal pages, absolute for external

Source Documents

  • 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.

Common Documentation Patterns

Protocol Specification Pages

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

Software Documentation

For software docs (NLWeb Core, Agent Finder):

  • Overview/motivation section
  • Quickstart guide with installation steps
  • API reference with examples
  • Use cases and best practices

Components

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.

Deployment

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

Contributing

When contributing documentation:

  1. Read the source specification documents (NLWEBSPEC.md, AGENTFINDER.md)
  2. Follow existing page structure and styling conventions
  3. Create new folders and page.mdx files for new pages
  4. Test locally before submitting changes
  5. Ensure all internal links work correctly

License

Please refer to the repository license file for licensing information.

Resources

  • 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

Support

For questions or issues:

  • File an issue in the GitHub repository
  • Check the FAQ at /docs/about/faq
  • Review the specification documentation