# 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

```bash
pnpm install
```

### Development

Run the development server:

```bash
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) to view the website.

### Build

Build the production-ready site:

```bash
pnpm build
```

### Start Production Server

```bash
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:**
```mdx
# Heading 1
## Heading 2
### Heading 3

Regular text with **bold** and *italic*.

- Bullet points
- More points

1. Numbered lists
2. Continue...
```

**Code Blocks:**
````mdx
```json
{
  "query": {
    "text": "example"
  }
}
```
````

**React Components:**
```mdx
<YourComponent prop="value" />
```

#### 3. Test Your Changes

Run the development server to see your changes live:
```bash
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:

```mdx
# 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](https://github.com/nlweb-ai)
- **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