WollyCMS

https://docs.wollycms.com
Admin
A self-hosted, open source headless CMS built for Astro with block-based composition, visual page...
Tokens:50,318
Snippets:607
Trust Score:2.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install and run the CMS server

Source: https://docs.wollycms.com/getting-started/quick-start

Installs dependencies, runs database migrations, seeds initial data, and starts the development server.

```bash
npm install
npm run migrate
npm run seed
npm run dev
```

--------------------------------

### Start WollyCMS Server

Source: https://docs.wollycms.com/deployment/nodejs

Launch the application server.

```bash
npm start
```

--------------------------------

### Install Ollama

Source: https://docs.wollycms.com/concepts/ai-helpers

Command to install the Ollama service on a local machine.

```bash
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Start WollyCMS Containers

Source: https://docs.wollycms.com/deployment/docker

Command to start the application containers in detached mode.

```bash

docker compose up -d

```

--------------------------------

### Install WollyCMS

Source: https://docs.wollycms.com/deployment/nodejs

Initialize a new WollyCMS project using the CLI tool.

```bash
npx create-wolly@latest my-cms
cd my-cms
npm install
```

--------------------------------

### GET /menus

Source: https://docs.wollycms.com/api/admin-api

List all menus.

```APIDOC
## GET /menus

### Description
List all menus

### Method
GET

### Endpoint
/menus
```

--------------------------------

### Install WollyCMS Astro package

Source: https://docs.wollycms.com/astro/setup

Install the required package via npm.

```bash
npm install @wollycms/astro
```

--------------------------------

### Astro Layout Example

Source: https://docs.wollycms.com/concepts/tracking

This example shows how to fetch and inject tracking scripts into an Astro page.

```astro
---
import { getWolly } from '../lib/wolly';


const scripts = await getWolly().tracking.list();
const headScripts = scripts.filter(s => s.position === 'head');
const bodyScripts = scripts.filter(s => s.position === 'body');
---


<html>
  <head>
    {headScripts.map(s => <Fragment set:html={s.code} />)}
  </head>
  <body>
    <slot />
    {bodyScripts.map(s => <Fragment set:html={s.code} />)}
  </body>
</html>

```

--------------------------------

### Initialize migration project

Source: https://docs.wollycms.com/migration/from-drupal

Commands to create the project directory and install necessary dependencies.

```bash
mkdir drupal-migration && cd drupal-migration
npm init -y
npm install mysql2 node-fetch
```

--------------------------------

### Initialize the Astro frontend

Source: https://docs.wollycms.com/getting-started/quick-start

Creates a new Astro project and installs the WollyCMS Astro integration package.

```bash
npm create astro@latest my-frontend
cd my-frontend
npm install @wollycms/astro
```

--------------------------------

### Get menu via GET

Source: https://docs.wollycms.com/api/content-api

Retrieves a menu structure by its slug, supporting depth limiting via the depth query parameter.

```bash
curl "http://localhost:4321/api/content/menus/main-nav"
```

--------------------------------

### Resolve better-sqlite3 installation issues

Source: https://docs.wollycms.com/getting-started/quick-start

Commands to fix native module compilation errors by using the recommended Node.js version or installing build tools.

```bash
nvm install 22
nvm use 22
npm install    # retry
```

```bash
# Ubuntu / Debian
sudo apt install build-essential python3


# macOS
xcode-select --install


# Windows
npm install -g windows-build-tools
```

```bash
npm rebuild better-sqlite3
```

--------------------------------

### Manage Processes with PM2

Source: https://docs.wollycms.com/deployment/nodejs

Install PM2 and configure the application for production process management.

```bash
npm install -g pm2
```

```javascript
module.exports = {
  apps: [{
    name: 'wollycms',
    script: 'node_modules/@wollycms/server/dist/index.js',
    env: {
      NODE_ENV: 'production',
      PORT: 4321,
      HOST: '0.0.0.0',
    },
    instances: 1,
    autorestart: true,
    max_memory_restart: '512M',
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
  }],
};
```

```bash
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup   # Auto-start on boot
```

--------------------------------

### Fetching a menu

Source: https://docs.wollycms.com/astro/menus

Example of how to fetch a menu using the createClient function.

```javascript
import { createClient } from '@wollycms/astro';


const wolly = createClient({ apiUrl: import.meta.env.CMS_API_URL });
const menu = await wolly.menus.get('main-nav');
```

--------------------------------

### Start database and import dump

Source: https://docs.wollycms.com/migration/from-drupal

Commands to launch the container and import the SQL dump file into the Drupal database.

```bash
docker compose up -d
# Wait for MySQL to be ready, then import:
docker exec -i drupal-db mysql -uroot -pmigration drupal < your-drupal-dump.sql
```

--------------------------------

### POST /api/admin/auth/2fa/setup

Source: https://docs.wollycms.com/concepts/two-factor-auth

Begins the 2FA setup process for an authenticated user, returning the QR code URI and secret.

```APIDOC
## POST /api/admin/auth/2fa/setup

### Description
Begins the 2FA setup process. Returns the QR code URI and secret for the user to configure their authenticator app.

### Method
POST

### Endpoint
/api/admin/auth/2fa/setup
```

--------------------------------

### GET /media/folders

Source: https://docs.wollycms.com/api/admin-api

List distinct media folders.

```APIDOC
## GET /media/folders

### Description
List distinct folders

### Method
GET

### Endpoint
/media/folders
```

--------------------------------

### Create term with fields

Source: https://docs.wollycms.com/concepts/taxonomies

Example of creating a term with custom fields.

```bash
curl -X POST http://localhost:4321/api/admin/taxonomies/1/terms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tutorials",
    "slug": "tutorials",
    "weight": 0,
    "fields": { "color": "#10b981", "icon": "book-open" }
  }'
```

--------------------------------

### GET /export

Source: https://docs.wollycms.com/api/admin-api

Exports site content and configuration to a JSON file.

```APIDOC
## GET /export

### Description
Returns a JSON file containing all site content and configuration for backups or migrations.

### Method
GET

### Endpoint
/export

### Response
#### Success Response (200)
- **JSON file** (object) - Contains site content, configuration, and metadata.
```

--------------------------------

### POST /api/admin/auth/2fa/verify-setup

Source: https://docs.wollycms.com/concepts/two-factor-auth

Confirms the 2FA setup by verifying the first TOTP code and returns the recovery codes.

```APIDOC
## POST /api/admin/auth/2fa/verify-setup

### Description
Confirms the 2FA setup by verifying the first TOTP code. Returns the recovery codes upon success.

### Method
POST

### Endpoint
/api/admin/auth/2fa/verify-setup
```

--------------------------------

### Hero component implementation

Source: https://docs.wollycms.com/astro/block-renderer

Example of accessing block fields to render a hero section.

```astro
---
const { fields, block, region, position } = Astro.props;


const heading = fields.heading as string;
const description = fields.description as string | undefined;
const ctaText = fields.cta_text as string | undefined;
const ctaUrl = fields.cta_url as string | undefined;
---


<section class="hero">
  <h1>{heading}</h1>
  {description && <p>{description}</p>}
  {ctaText && ctaUrl && (
    <a href={ctaUrl} class="btn">{ctaText}</a>
  )}
</section>
```

--------------------------------

### Render menu in Astro

Source: https://docs.wollycms.com/concepts/menus

Example implementation of a navigation component using WollyCMS menu helpers in an Astro project.

```astro
---
import { createClient, menuHelpers } from '@wollycms/astro';


const wolly = createClient({ apiUrl: import.meta.env.CMS_API_URL });
const menu = await wolly.menus.get('main-nav');
const currentPath = Astro.url.pathname;
---


<nav>
  <ul>
    {menu.items.map((item) => {
      const href = menuHelpers.getItemHref(item);
      const active = menuHelpers.isActive(item, currentPath);
      return (
        <li class:list={[{ active }]}>
          {href ? (
            <a href={href} target={item.target}>{item.title}</a>
          ) : (
            <span>{item.title}</span>
          )}
          {item.children.length > 0 && (
            <ul>
              {item.children.map((child) => (
                <li>
                  <a href={menuHelpers.getItemHref(child)}>{child.title}</a>
                </li>
              ))}
            </ul>
          )}
        </li>
      );
    })}
  </ul>
</nav>
```

--------------------------------

### GET /menus/:slug

Source: https://docs.wollycms.com/api/content-api

Retrieves a menu structure by its slug.

```APIDOC
## GET /menus/:slug

### Description
Returns a menu with its full nested item tree.

### Method
GET

### Endpoint
/menus/:slug

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique slug of the menu
#### Query Parameters
- **depth** (number) - Optional - Limit nesting depth
```

--------------------------------

### GET /media

Source: https://docs.wollycms.com/api/admin-api

List media files with optional filtering and sorting.

```APIDOC
## GET /media

### Description
List media. Filters: ?type=, ?search=, ?folder=, ?sort=, ?order=

### Method
GET

### Endpoint
/media
```

--------------------------------

### Footer navigation

Source: https://docs.wollycms.com/astro/menus

Example of rendering footer navigation.

```astro
---
const footer = await wolly.menus.get('footer');
---


<footer>
  <div class="footer-columns">
    {footer.items.map((column) => (
      <div class="footer-column">
        <h3>{column.title}</h3>
        <ul>
          {column.children.map((link) => (
            <li>
              <a href={menuHelpers.getItemHref(link)} target={link.target}>
                {link.title}
              </a>
            </li>
          ))}
        </ul>
      </div>
    ))}
  </div>
</footer>
```

--------------------------------

### Configure Cloudflare Workers

Source: https://docs.wollycms.com/astro/setup

Setup the Cloudflare adapter and runtime-aware client for deployment.

```bash
npm install @astrojs/cloudflare
```

```typescript
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';


export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});
```

```typescript
import { createClient } from '@wollycms/astro';
import { env } from 'cloudflare:workers';


const buildTimeUrl = import.meta.env.CMS_API_URL || '';


export function getWolly() {
  const apiUrl = env?.CMS_API_URL
    || buildTimeUrl
    || 'http://localhost:4321/api/content';


  return createClient({ apiUrl });
}
```

```astro
---
import { getWolly } from '../lib/wolly';


const wolly = getWolly();
const page = await wolly.pages.getBySlug('home');
---
```

```toml
[vars]
CMS_API_URL = "https://cms.example.com/api/content"
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://docs.wollycms.com/deployment/docker

Example Caddyfile configuration to proxy traffic to the WollyCMS container.

```text

# Caddyfile
cms.example.com {
    reverse_proxy wollycms:4321
}

```

--------------------------------

### Create a taxonomy

Source: https://docs.wollycms.com/concepts/taxonomies

Example of creating a new taxonomy using a curl command.

```bash
curl -X POST http://localhost:4321/api/admin/taxonomies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Category",
    "slug": "category",
    "description": "Blog post categories",
    "hierarchical": false
  }'
```

--------------------------------

### Menu data structure

Source: https://docs.wollycms.com/concepts/menus

Example of the JSON object returned by the menu API.

```json
{
  "id": 1,
  "name": "Main Navigation",
  "slug": "main-nav",
  "items": [
    {
      "id": 1,
      "title": "Home",
      "url": null,
      "page_slug": "home",
      "target": "_self",
      "attributes": null,
      "children": []
    },
    {
      "id": 2,
      "title": "Products",
      "url": null,
      "page_slug": "products",
      "target": "_self",
      "attributes": null,
      "children": [
        {
          "id": 3,
          "title": "WollyCMS",
          "url": null,
          "page_slug": "products/wollycms",
          "target": "_self",
          "attributes": null,
          "children": []
        }
      ]
    },
    {
      "id": 4,
      "title": "GitHub",
      "url": "https://github.com/wollycms",
      "page_slug": null,
      "target": "_blank",
      "attributes": { "class": "external" },
      "children": []
    }
  ]
}
```

--------------------------------

### Configure WordPress URL redirects

Source: https://docs.wollycms.com/migration/from-wordpress

Example patterns for handling legacy WordPress URL structures within Astro middleware or redirect configuration files.

```text
// In your Astro middleware or _redirects file:
// /?p=123           → /actual-slug
// /category/news/   → /blog (or taxonomy page)
// /wp-content/...   → 404 or redirect to WollyCMS media
```

--------------------------------

### Before Hook Handlers

Source: https://docs.wollycms.com/concepts/lifecycle-hooks

Examples of transforming input data and blocking operations using before hooks.

```javascript
// Transform data before save
hooks.on('beforeCreate', async ({ data }) => {
  if (data?.title) {
    data.title = String(data.title).trim();
  }
});


// Block deletion of important pages
hooks.on('beforeDelete', async ({ entity }) => {
  if (entity?.slug === 'home') {
    throw new Error('Cannot delete the home page');
  }
});
```

--------------------------------

### List pages via GET

Source: https://docs.wollycms.com/api/content-api

Retrieves a list of published pages with optional filtering and pagination.

```bash
curl "http://localhost:4321/api/content/pages?type=blog_post&limit=5"
```

--------------------------------

### Using API keys in Astro frontend

Source: https://docs.wollycms.com/concepts/api-keys

Example of how to use an API key to initialize the WollyCMS client in an Astro frontend.

```javascript
import { createClient } from '@wollycms/astro';


const wolly = createClient({
  apiUrl: 'https://your-cms.example.com/api/content',
  apiKey: 'sk_your_api_key_here', // optional — for authenticated requests
});

```

--------------------------------

### Rich Text component implementation

Source: https://docs.wollycms.com/astro/block-renderer

Example of using the RichText component to render TipTap JSON content.

```astro
---
import RichText from '@wollycms/astro/components/RichText.astro';


const { fields } = Astro.props;
---


<div class="prose">
  <RichText content={fields.body} />
</div>
```

--------------------------------

### Create hierarchical terms

Source: https://docs.wollycms.com/concepts/taxonomies

Examples of creating parent and child terms for a hierarchical taxonomy.

```bash
# Create parent term
curl -X POST http://localhost:4321/api/admin/taxonomies/2/terms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "North America", "slug": "north-america", "weight": 0 }'


# Create child term
curl -X POST http://localhost:4321/api/admin/taxonomies/2/terms \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "United States", "slug": "united-states", "parentId": 1, "weight": 0 }'
```

--------------------------------

### Rendering a navigation bar

Source: https://docs.wollycms.com/astro/menus

Example of rendering a navigation bar using menu helpers.

```astro
---
import { createClient, menuHelpers } from '@wollycms/astro';


const wolly = createClient({ apiUrl: import.meta.env.CMS_API_URL });
const menu = await wolly.menus.get('main-nav');
const currentPath = Astro.url.pathname;
---


<nav aria-label="Main navigation">
  <ul>
    {menu.items.map((item) => {
      const href = menuHelpers.getItemHref(item);
      const active = menuHelpers.isActive(item, currentPath);
      return (
        <li class:list={[{ active }]}>
          {href ? (
            <a href={href} target={item.target} aria-current={active ? 'page' : undefined}>
              {item.title}
            </a>
          ) : (
            <span>{item.title}</span>
          )}
          {item.children.length > 0 && (
            <ul class="submenu">
              {item.children.map((child) => (
                <li class:list={[{ active: menuHelpers.isActive(child, currentPath) }]}>
                  <a href={menuHelpers.getItemHref(child)} target={child.target}>
                    {child.title}
                  </a>
                </li>
              ))}
            </ul>
          )}
        </li>
      );
    })}
  </ul>
</nav>
```

--------------------------------

### Rendering breadcrumbs

Source: https://docs.wollycms.com/astro/menus

Example of rendering breadcrumbs using menu helpers.

```astro
---
import { createClient, menuHelpers } from '@wollycms/astro';


const wolly = createClient({ apiUrl: import.meta.env.CMS_API_URL });
const menu = await wolly.menus.get('main-nav');
const currentPath = Astro.url.pathname;
const breadcrumbs = menuHelpers.getBreadcrumbs(menu.items, currentPath);
---


{breadcrumbs.length > 0 && (
  <nav aria-label="Breadcrumb">
    <ol>
      <li><a href="/">Home</a></li>
      {breadcrumbs.map((crumb, i) => {
        const href = menuHelpers.getItemHref(crumb);
        const isLast = i === breadcrumbs.length - 1;
        return (
          <li>
            {isLast ? (
              <span aria-current="page">{crumb.title}</span>
            ) : (
              <a href={href}>{crumb.title}</a>
            )}
          </li>
        );
      })}
    </ol>
  </nav>
)}
```

--------------------------------

### GET /menus/:id

Source: https://docs.wollycms.com/api/admin-api

Get a menu with its item tree.

```APIDOC
## GET /menus/:id

### Description
Get menu with item tree

### Method
GET

### Endpoint
/menus/:id
```

--------------------------------

### Initialize WollyCMS Project

Source: https://docs.wollycms.com/deployment/docker

Commands to create a new project and prepare the environment configuration file.

```bash

# Create a project and enter it
npx create-wolly@latest my-cms
cd my-cms


# Create your .env file
cp .env.example .env
# Edit .env and set a strong JWT_SECRET

```

--------------------------------

### GET /media/:id

Source: https://docs.wollycms.com/api/admin-api

Get single media details with URLs.

```APIDOC
## GET /media/:id

### Description
Get single media with URLs

### Method
GET

### Endpoint
/media/:id
```

--------------------------------

### Rendering a tag list

Source: https://docs.wollycms.com/concepts/taxonomies

Example of rendering a list of terms in Astro, fetching them first and then mapping over them.

```astro
---
const categories = await wolly.taxonomies.getTerms('category');
---


<ul>
  {categories.map((term) => (
    <li>
      <a href={`/blog?category=${term.slug}`}>{term.name}</a>
    </li>
  ))}
</ul>
```

--------------------------------

### General AI Completion Request

Source: https://docs.wollycms.com/concepts/ai-helpers

Example POST request to the general completion endpoint for custom AI tasks.

```json
POST /api/admin/ai/complete
{
  "prompt": "Summarize this article in 2 sentences: ...",
  "systemPrompt": "You are a content editor.",
  "maxTokens": 200,
  "temperature": 0.5
}
```

--------------------------------

### Heading anchor HTML output

Source: https://docs.wollycms.com/astro/rich-text

Example of the rendered HTML for a heading with an anchor ID and focusable tabindex.

```html
<h2 id="student-stories" tabindex="-1">Student Stories</h2>
```

--------------------------------

### Fetching terms in Astro

Source: https://docs.wollycms.com/concepts/taxonomies

Example of fetching all terms in a specific taxonomy using the Astro client.

```javascript
const wolly = createClient({ apiUrl: import.meta.env.CMS_API_URL });


// Get all terms in the "category" taxonomy
const categories = await wolly.taxonomies.getTerms('category');
```

--------------------------------

### Initialize project with template using create-wolly

Source: https://docs.wollycms.com/getting-started/templates

Use the create-wolly CLI to bootstrap a new project with a specific template and run necessary migration and import scripts.

```bash
npx create-wolly@latest my-site --template blog
cd my-site
npm run migrate
npm run import -- seed.json
npm run dev
```

--------------------------------

### Render SEO tags in Astro layout

Source: https://docs.wollycms.com/astro/seo

Example of integrating SEO metadata into an Astro component's head section.

```astro
---
import { seoHelpers } from '@wollycms/astro';


const { page } = Astro.props;
const config = await wolly.config.get();
const seo = seoHelpers.getPageSeo(page, config);
const siteUrl = import.meta.env.SITE_URL || 'https://example.com';
---


<html>
  <head>
    <title>{seo.title}</title>
    {seo.description && <meta name="description" content={seo.description} />}
    {seo.robots && <meta name="robots" content={seo.robots} />}
    {seo.canonicalUrl && <link rel="canonical" href={seo.canonicalUrl} />}


    <!-- Open Graph -->
    <meta property="og:title" content={seo.title} />
    {seo.description && <meta property="og:description" content={seo.description} />}
    {seo.ogImage && <meta property="og:image" content={seo.ogImage} />}
    <meta property="og:url" content={`${siteUrl}/${page.slug}`} />
    <meta property="og:type" content="website" />
  </head>
  <body>
    <slot />
  </body>
</html>
```

--------------------------------

### Run Migrations and Seed

Source: https://docs.wollycms.com/deployment/nodejs

Prepare the database schema and initial data.

```bash
npm run migrate
npm run seed
```

--------------------------------

### Get single page via GET

Source: https://docs.wollycms.com/api/content-api

Retrieves a single published page by its slug, including resolved blocks and SEO metadata.

```bash
curl "http://localhost:4321/api/content/pages/about"
```

--------------------------------

### Create Cloudflare D1 and R2 resources

Source: https://docs.wollycms.com/deployment/cloudflare

Initialize the database and storage bucket required for the CMS.

```bash
# Create the D1 database
wrangler d1 create wollycms-db


# Create the R2 bucket
wrangler r2 create wollycms-media
```

--------------------------------

### Setting up preview in Astro

Source: https://docs.wollycms.com/concepts/preview

Your Astro frontend needs to handle preview requests. The `@wollycms/astro` package provides helpers.

```astro
---\nimport { getWolly } from '../../lib/wolly';
import * as blocks from '../../lib/blocks';
import BlockRenderer from '@wollycms/astro/components/BlockRenderer.astro';
import Layout from '../../layouts/Default.astro';


const token = Astro.url.searchParams.get('token');
const slug = Astro.params.slug || 'home';


// Fetch draft content using preview token
const wolly = getWolly();
const page = await wolly.pages.preview(slug, token);
---\n

<Layout title={page.title}>
  <BlockRenderer blocks={page.regions.content ?? []} components={blocks} />
</Layout>

```

--------------------------------

### GET /blocks

Source: https://docs.wollycms.com/api/admin-api

List reusable blocks with optional filtering.

```APIDOC
## GET /blocks

### Description
List reusable blocks. Filters: ?type=, ?search=, ?reusable=false

### Method
GET

### Endpoint
/blocks
```

--------------------------------

### Scaffold a new WollyCMS project

Source: https://docs.wollycms.com/getting-started/quick-start

Initializes a new project directory with the necessary dependencies and configuration files.

```bash
npx create-wolly@latest my-site
cd my-site
```

--------------------------------

### GET /api/admin/auth/oauth/providers

Source: https://docs.wollycms.com/concepts/oauth

Retrieves a list of configured OAuth providers.

```APIDOC
## GET /api/admin/auth/oauth/providers

### Description
Returns which OAuth providers are currently configured for the system.

### Method
GET

### Endpoint
/api/admin/auth/oauth/providers
```

--------------------------------

### GET /search

Source: https://docs.wollycms.com/api/content-api

Searches published pages by title and slug.

```APIDOC
## GET /search

### Description
Searches published pages by title and slug. Requires a minimum of 2 characters.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query
- **type** (string) - Optional - Filter by content type
- **limit** (number) - Optional - Max results (max 50, default: 20)
```

--------------------------------

### Build and deploy WollyCMS

Source: https://docs.wollycms.com/deployment/cloudflare

Commands to build the admin UI and worker, run migrations, and deploy to Cloudflare.

```bash
# Build the admin UI
npm run build:admin
mkdir -p packages/admin/build-assets/admin
cp -r packages/admin/build/* packages/admin/build-assets/admin/
cp packages/admin/build/index.html packages/admin/build-assets/index.html


# Build the Worker bundle
npm run build:worker


# Apply every pending D1 migration
npx wrangler d1 migrations apply wollycms-db --remote


# Deploy to Cloudflare
npx wrangler deploy
```

--------------------------------

### Initialize WollyCMS client

Source: https://docs.wollycms.com/astro/setup

Create a client instance in your project. Ensure the CMS_API_URL environment variable is set.

```typescript
import { createClient } from '@wollycms/astro';


export const wolly = createClient({
  apiUrl: import.meta.env.CMS_API_URL || 'http://localhost:4321/api/content',
});
```

```text
CMS_API_URL=http://localhost:4321/api/content
```

--------------------------------

### GET /users

Source: https://docs.wollycms.com/api/admin-api

Retrieves a list of all users, excluding password hashes.

```APIDOC
## GET /users

### Description
List all users in the system. Password hashes are excluded from the response.

### Method
GET

### Endpoint
/users
```

--------------------------------

### Registering hooks at startup

Source: https://docs.wollycms.com/concepts/lifecycle-hooks

Import the hooks instance and register logic in the server entry point or a dedicated hooks file.

```typescript

import { hooks } from './hooks.js';


hooks.on('beforePublish', async ({ data }) => {
  // Your custom logic
});


```

--------------------------------

### Configure Local Filesystem Storage

Source: https://docs.wollycms.com/concepts/media

Set environment variables to store media files on the local server disk.

```bash
MEDIA_STORAGE=local
MEDIA_DIR=./uploads
```

--------------------------------

### GET /api/admin/pages

Source: https://docs.wollycms.com/concepts/i18n

Retrieve a list of pages, optionally filtered by locale.

```APIDOC
## GET /api/admin/pages

### Description
Retrieve a list of pages. Use the locale query parameter to filter results by a specific language.

### Method
GET

### Endpoint
/api/admin/pages

### Parameters
#### Query Parameters
- **locale** (string) - Optional - The locale code to filter pages by.
```

--------------------------------

### Health Check Response

Source: https://docs.wollycms.com/deployment/docker

Example JSON response from the /api/health endpoint.

```json
{
  "status": "ok",
  "version": "0.3.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T12:00:00.000Z",
  "cache": { "entries": 42 }
}
```

--------------------------------

### Configure S3-Compatible Storage

Source: https://docs.wollycms.com/concepts/media

Set environment variables to use S3-compatible services like AWS or MinIO for media storage.

```bash
MEDIA_STORAGE=s3
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
S3_BUCKET=my-media-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY=AKIA...
S3_SECRET_KEY=...
S3_PUBLIC_URL=https://cdn.example.com
```

--------------------------------

### GET /api/admin/auth/oauth/connections

Source: https://docs.wollycms.com/concepts/oauth

Lists all OAuth accounts currently connected to the authenticated user.

```APIDOC
## GET /api/admin/auth/oauth/connections

### Description
Returns a list of OAuth accounts connected to the current user session.

### Method
GET

### Endpoint
/api/admin/auth/oauth/connections
```

--------------------------------

### Configure PostgreSQL database

Source: https://docs.wollycms.com/getting-started/quick-start

Alternative database configuration to avoid native module compilation.

```text
DATABASE_URL=postgresql://user:password@localhost:5432/wollycms
```

--------------------------------

### GET /api/admin/auth/oauth/:provider/callback

Source: https://docs.wollycms.com/concepts/oauth

Handles the OAuth callback from the provider and issues a session.

```APIDOC
## GET /api/admin/auth/oauth/:provider/callback

### Description
Processes the callback from the OAuth provider and issues a session upon successful authentication.

### Method
GET

### Endpoint
/api/admin/auth/oauth/:provider/callback

### Parameters
#### Path Parameters
- **provider** (string) - Required - The identifier of the OAuth provider.
```

--------------------------------

### GET /api/admin/pages/:id/translations

Source: https://docs.wollycms.com/concepts/i18n

List all translations associated with a specific page group.

```APIDOC
## GET /api/admin/pages/:id/translations

### Description
Retrieve a list of all pages belonging to the same translation group as the specified page ID.

### Method
GET

### Endpoint
/api/admin/pages/:id/translations
```

--------------------------------

### GET /api/admin/ai/status

Source: https://docs.wollycms.com/concepts/ai-helpers

Checks if the AI provider is correctly configured in the system settings.

```APIDOC
## GET /api/admin/ai/status

### Description
Checks if AI is configured and returns the currently active provider and model.

### Method
GET

### Endpoint
/api/admin/ai/status
```

--------------------------------

### Implement catch-all route

Source: https://docs.wollycms.com/astro/setup

Use the BlockRenderer component to dynamically render page content based on the slug.

```astro
---
import Layout from '../layouts/Default.astro';
import BlockRenderer from '@wollycms/astro/components/BlockRenderer.astro';
import { wolly } from '../lib/wolly';
import * as blocks from '../lib/blocks';


const slug = Astro.params.slug || 'home';
const page = await wolly.pages.getBySlug(slug);
---


<Layout title={page.title}>
  <BlockRenderer blocks={page.regions.hero ?? []} region="hero" components={blocks} />
  <BlockRenderer blocks={page.regions.content ?? []} region="content" components={blocks} />
</Layout>
```

--------------------------------

### Configure PostgreSQL Database

Source: https://docs.wollycms.com/deployment/nodejs

Set the connection string for a PostgreSQL database.

```text
DATABASE_URL=postgresql://wolly:password@localhost:5432/wollycms
```

--------------------------------

### Regions field structure

Source: https://docs.wollycms.com/api/graphql

Example of the JSON structure returned by the regions field.

```json
{
  "hero": [{ "block_type": "hero", "fields": { "heading": "..." } }],
  "content": [{ "block_type": "rich_text", "fields": { "body": "..." } }]
}
```

--------------------------------

### Import SpacelyImage Component

Source: https://docs.wollycms.com/getting-started/upgrading-to-0-3

Use the new responsive image component in Astro files.

```astro
---
import SpacelyImage from '@wollycms/astro/components/SpacelyImage.astro';
---
```

--------------------------------

### POST /menus

Source: https://docs.wollycms.com/api/admin-api

Create a new menu.

```APIDOC
## POST /menus

### Description
Create a new menu.

### Method
POST

### Endpoint
/menus

### Request Body
- **name** (string) - Required
- **slug** (string) - Required
```

--------------------------------

### GET /blocks/:id

Source: https://docs.wollycms.com/api/admin-api

Retrieve a specific block by ID including usage information.

```APIDOC
## GET /blocks/:id

### Description
Get block with usage info

### Method
GET

### Endpoint
/blocks/:id
```

--------------------------------

### POST /batch

Source: https://docs.wollycms.com/api/content-api

Fetches multiple pages and menus in a single request.

```APIDOC
## POST /batch

### Description
Fetch multiple pages and menus in one request.

### Method
POST

### Endpoint
/batch

### Request Body
- **pages** (array) - Optional - List of page slugs (max 50)
- **menus** (array) - Optional - List of menu slugs (max 10)
```

--------------------------------

### GET /pages

Source: https://docs.wollycms.com/api/content-api

Returns a list of published pages with support for filtering, sorting, and pagination.

```APIDOC
## GET /pages

### Description
Returns published pages with filtering, sorting, and pagination.

### Method
GET

### Endpoint
/pages

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by content type slug
- **taxonomy** (string) - Optional - Filter by taxonomy (e.g., category:news)
- **sort** (string) - Optional - Sort field and direction (default: published_at:desc)
- **limit** (number) - Optional - Results per page (max 50, default: 20)
- **offset** (number) - Optional - Pagination offset (default: 0)

### Response
#### Success Response (200)
- **data** (array) - List of page objects
- **meta** (object) - Pagination metadata
```

--------------------------------

### Deploy Astro frontend to Cloudflare

Source: https://docs.wollycms.com/deployment/cloudflare

Steps to configure and deploy an Astro frontend to Cloudflare Workers.

```bash
# In your Astro frontend project
npm install @astrojs/cloudflare
```

```javascript
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';


export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});
```

```toml
# wrangler.toml for the Astro frontend
name = "my-site"
compatibility_date = "2026-07-31"
compatibility_flags = ["nodejs_compat"]


[vars]
CMS_API_URL = "https://cms.example.com/api/content"
```

```bash
npm run build
npx wrangler deploy dist/server/entry.mjs --assets dist/client
```

--------------------------------

### After Hook Handler

Source: https://docs.wollycms.com/concepts/lifecycle-hooks

Example of performing a side effect, such as a Slack notification, after a database operation.

```javascript
// Send Slack notification on new page
hooks.on('afterCreate', async ({ entity, user }) => {
  await fetch(SLACK_WEBHOOK_URL, {
    method: 'POST',
    body: JSON.stringify({
      text: `${user?.email} created "${entity?.title}"`,
    }),
  });
});
```

--------------------------------

### Configure Environment Variables

Source: https://docs.wollycms.com/deployment/docker

Required environment variables for the .env file.

```text

JWT_SECRET=your-generated-secret-here
SITE_URL=https://your-site.example.com
CORS_ORIGINS=https://your-site.example.com

```

--------------------------------

### GET /api/content/config

Source: https://docs.wollycms.com/concepts/i18n

Retrieves the site's locale configuration, including default and supported locales.

```APIDOC
## GET /api/content/config

### Description
Retrieves the site's locale configuration, including default and supported locales.

### Method
GET

### Endpoint
/api/content/config

### Response
#### Success Response (200)
- **defaultLocale** (string) - The site's default locale.
- **supportedLocales** (array) - A list of supported locale codes.
```

--------------------------------

### Configure PostgreSQL Database

Source: https://docs.wollycms.com/deployment/docker

Docker Compose snippet to switch from SQLite to a PostgreSQL database service.

```yaml

services:
  wollycms:
    environment:
      - DATABASE_URL=postgresql://wolly:password@db:5432/wollycms
    depends_on:
      db:
        condition: service_healthy


  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: wolly
      POSTGRES_PASSWORD: password
      POSTGRES_DB: wollycms
    volumes:
      - pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wolly"]
      interval: 10s
      timeout: 5s
      retries: 5


volumes:
  wolly-data:
  wolly-uploads:
  pg-data:

```

--------------------------------

### Implementing Responsive Srcset

Source: https://docs.wollycms.com/astro/images

Building a responsive srcset attribute by fetching media info and mapping variants.

```astro
---
import SpacelyImage from '@wollycms/astro/components/SpacelyImage.astro';


const mediaId = fields.image as number;
const info = await wolly.media.getInfo(mediaId);


const srcset = [
  `${wolly.media.url(mediaId, 'medium')} 800w`,
  `${wolly.media.url(mediaId, 'large')} 1200w`,
  `${wolly.media.url(mediaId, 'original')} ${info.width}w`,
].join(', ');
---


<SpacelyImage
  src={wolly.media.url(mediaId, 'large')}
  srcset={srcset}
  sizes="(max-width: 800px) 100vw, 1200px"
  alt={info.altText || ''}
  width={info.width}
  height={info.height}
/>
```

--------------------------------

### Filtering content by taxonomy

Source: https://docs.wollycms.com/concepts/taxonomies

Examples of filtering pages by taxonomy using the content API.

```javascript
// All pages in the "tutorials" category
const tutorials = await wolly.pages.list({
  taxonomy: 'category:tutorials',
});


// All pages that have any term in the "tags" vocabulary
const tagged = await wolly.pages.list({
  taxonomy: 'tags',
});
```

--------------------------------

### Docker Compose Configuration

Source: https://docs.wollycms.com/deployment/docker

Standard docker-compose.yml file for running WollyCMS with SQLite.

```yaml

services:
  wollycms:
    image: ghcr.io/wollycms/wollycms:0.3.0
    ports:
      - "4321:4321"
    environment:
      - NODE_ENV=production
      - PORT=4321
      - HOST=0.0.0.0
      - DATABASE_URL=sqlite:./data/wolly.db
      - MEDIA_DIR=./uploads
      - JWT_SECRET=${JWT_SECRET:?Set JWT_SECRET in .env}
      - CORS_ORIGINS=${CORS_ORIGINS:-*}
      - RATE_LIMIT_AUTH=${RATE_LIMIT_AUTH:-10}
      - RATE_LIMIT_WINDOW_MS=${RATE_LIMIT_WINDOW_MS:-900000}
      - SITE_URL=${SITE_URL:-http://localhost:4322}
    volumes:
      - wolly-data:/app/data
      - wolly-uploads:/app/uploads
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:4321/api/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3


volumes:
  wolly-data:
  wolly-uploads:

```

--------------------------------

### Generated Anchor Name

Source: https://docs.wollycms.com/concepts/heading-anchors

Example of an anchor name generated from a heading titled Student Stories.

```text
student-stories
```

--------------------------------

### Deploy to Cloudflare Workers

Source: https://docs.wollycms.com/getting-started/upgrading-to-0-3

Build the project, apply D1 database migrations, and deploy to the Cloudflare environment.

```bash
npm ci
npm run build:admin
npm run build:worker
npx wrangler d1 migrations apply <database-name> --remote
npx wrangler deploy
```

--------------------------------

### Query site configuration

Source: https://docs.wollycms.com/api/graphql

Retrieve global site settings and locale information.

```graphql
{
  config {
    siteName
    tagline
    logo
    defaultLocale
    supportedLocales
  }
}
```

--------------------------------

### POST /api/admin/auth/login

Source: https://docs.wollycms.com/concepts/two-factor-auth

Initiates the login process. If 2FA is enabled for the user, it returns a challenge token required for the verification step.

```APIDOC
## POST /api/admin/auth/login

### Description
Initiates the login process. If 2FA is enabled for the user, the response indicates that a challenge token is required to proceed.

### Method
POST

### Endpoint
/api/admin/auth/login
```

--------------------------------

### Configure baseUrl for split-origin deployments

Source: https://docs.wollycms.com/astro/rich-text

Provide a baseUrl to resolve relative media paths when the CMS and frontend are hosted on different origins.

```astro
<RichText content={fields.body} baseUrl="https://cms.example.com" />
```

```javascript
const html = renderRichText(fields.body, 'https://cms.example.com');
```

--------------------------------

### GET /api/admin/auth/oauth/:provider

Source: https://docs.wollycms.com/concepts/oauth

Initiates the OAuth flow by redirecting the user to the provider's consent screen.

```APIDOC
## GET /api/admin/auth/oauth/:provider

### Description
Redirects the user to the specified provider's consent screen to begin the authentication process.

### Method
GET

### Endpoint
/api/admin/auth/oauth/:provider

### Parameters
#### Path Parameters
- **provider** (string) - Required - The identifier of the OAuth provider.
```
Tokens:
Raw