Customization

Access Control

Access ControlBeta

Protect your documentation pages with authentication. Control who can see what — from simple password protection to full OAuth with role-based access.

Overview

xyd access control provides:

Page-level protection — mark pages as public or protected via frontmatter or pattern rules
Group-based access — restrict pages to specific roles (admin, premium, etc.)
SSR exclusion — protected content never appears in HTML source
Edge middleware — server-side protection for Netlify, Vercel, Cloudflare, or standalone Node.js
Search filtering — protected pages excluded from search for unauthorized users
Sidebar filtering — protected nav items hidden from unauthorized users

Quick Start

Add accessControl to your docs.json:

{
  "accessControl": {
    "provider": {
      "type": "jwt",
      "loginUrl": "https://your-auth-server.com/login",
      "algorithm": "HS256",
      "secret": "$AUTH_SECRET",
      "groupsClaim": "groups"
    },
    "defaultAccess": "public",
    "rules": [
      { "match": "/api/**", "access": "protected" },
      { "match": "/admin/**", "access": "protected", "groups": ["admin"] }
    ]
  }
}

Auth Providers

JWT

External login server signs a JWT and redirects back to your docs with the token.

{
  "provider": {
    "type": "jwt",
    "loginUrl": "https://auth.example.com/login",
    "callbackPath": "/auth/jwt-callback",
    "algorithm": "HS256",
    "secret": "$AUTH_SECRET",
    "groupsClaim": "groups"
  }
}

OAuth 2.0

Redirect to an OAuth provider (Auth0, Google, GitHub, etc.) for authentication.

{
  "provider": {
    "type": "oauth",
    "authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
    "tokenUrl": "https://oauth2.googleapis.com/token",
    "clientId": "$OAUTH_CLIENT_ID",
    "scopes": ["openid", "email"],
    "callbackPath": "/auth/callback",
    "userInfoUrl": "https://api.example.com/userinfo",
    "groupsClaim": "roles"
  }
}

Password

Simple shared-password protection with an external password form.

{
  "provider": {
    "type": "jwt",
    "loginUrl": "https://your-password-server.com/login",
    "algorithm": "HS256",
    "secret": "$AUTH_SECRET"
  }
}

Page-Level Access

Frontmatter

Override access on individual pages:

---
title: Admin Guide
public: false
accessGroups: ["admin"]
---

Field	Effect
`public: true`	Always public, even if `defaultAccess` is `"protected"`
`public: false`	Always protected, even if `defaultAccess` is `"public"`
`accessGroups: ["admin"]`	Requires membership in at least one listed group

Pattern Rules

Match pages by glob pattern in docs.json:

{
  "rules": [
    { "match": "/guides/**", "access": "public" },
    { "match": "/api/**", "access": "protected" },
    { "match": "/admin/**", "access": "protected", "groups": ["admin"] }
  ]
}

Rules are evaluated in order — first match wins.

Evaluation Priority

Frontmatter (highest) — public / accessGroups in page metadata
Pattern rules — rules array in docs.json
Default access (lowest) — defaultAccess: "public" | "protected"

Edge Middleware

For production deployments, enable server-side protection:

{
  "accessControl": {
    "deploy": {
      "platform": "node-edge"
    }
  }
}

Platform	Description
`"node-edge"`	Standalone Node.js server (auto-generated by `xyd build`)
`"netlify-edge"`	Netlify Edge Functions
`"vercel-edge"`	Vercel Routing Middleware
`"cloudflare-edge"`	Cloudflare Pages Functions

Node.js Server

With deploy.platform: "node-edge", xyd build generates a server.mjs in your build output:

xyd build   # generates .xyd/build/client/server.mjs
xyd serve   # starts the server automatically

The server:

Verifies JWT signatures (HS256)
Checks access rules on every request
Returns 302 redirect for unauthorized users (even for curl)
Protects content chunks from direct access

Environment Variables

Variable	Required	Description
`AUTH_SECRET`	Yes (for JWT)	JWT signing secret (≥32 characters)
`PORT`	No	Server port (default: 3000)

Session Configuration

{
  "session": {
    "maxAge": 86400,
    "cookieName": "xyd-auth-token"
  }
}

xyd provides a built-in login page at /login. Customize it:

{
  "login": {
    "title": "Sign in to access docs",
    "description": "Enterprise documentation requires authentication.",
    "logo": "/images/logo.svg"
  }
}

Security Model

Layer	Protection	Platform
Layer 1 (default)	SSR exclusion + client-side auth. Content not in HTML source.	Any static host
Layer 2 (deploy)	Server-side JWT verification. Content never served to unauthorized.	Node.js, Netlify, Vercel, Cloudflare

CLI Commands

Command	Description
`xyd build`	Builds static site. With `deploy.platform: "node-edge"`, generates `server.mjs`.
`xyd serve`	Serves the built site in production. Auto-detects deploy mode.
`xyd dev`	Development server with access control middleware.

Examples

Edit page

Plugins Theme API