LumeCMS

https://lume.land/cms/
Admin
LumeCMS is a Deno-native content management system designed to easily manage and live-preview...
Tokens:14,809
Snippets:231
Trust Score:8.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example Post Frontmatter

Source: https://lume.land/cms/getting-started/collections

A sample Markdown file structure representing a single post within a collection.

```markdown
---
title: Static site generators are cool!
author: Óscar Otero
tags:
  - lume
  - ssg
---

I like static site generators because they are fast, flexible, and fun to work with.
```

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

### Configure collection document types

Source: https://lume.land/cms/configuration/collections

Examples of defining collection structures using object, object-list, and choose types.

```javascript
cms.collection({
  name: "notes",
  store: "src:*.json",
  type: "object", // default value, no need to specify
  fields: [
    "title: text",
    "text: textarea",
  ],
});
```

```json
{
  "title": "Note title",
  "text": "This is the note"
}
```

```javascript
cms.collection({
  name: "notes",
  store: "src:*.json",
  type: "object-list",
  fields: [
    "title: text",
    "text: textarea",
  ],
});
```

```json
[
  {
    "title": "First note",
    "text": "Text of the first note"
  },
  {
    "title": "Second note",
    "text": "Text of the second note"
  }
]
```

```javascript
cms.collection({
  name: "notes",
  store: "src:*.json",
  type: "choose",
  fields: [
    {
      name: "text"
      fields: [
        "title: text",
        "text: textarea",
      ]
    },
    {
      name: "image"
      fields: [
        "title: text",
        "image: file",
      ]
    }
  ],
});
```

```json
{
  "type": "text",
  "title": "Note title",
  "text": "This is the note"
}
```

```json
{
  "type": "image",
  "title": "My image",
  "image": "/images/photo-1.jpg"
}
```

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

### Example Markdown file structure

Source: https://lume.land/cms/getting-started/edit-a-file

A sample markdown file with front matter variables used for CMS configuration.

```markdown
---
layout: homepage.vto
title: Welcome to my site
description: I'm Óscar Otero, web designer and developer
---

## Hi there!

My name is Óscar Otero and this is my personal website.
```

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

### Example data structure

Source: https://lume.land/cms/fields/object

A representation of the data structure being grouped.

```yaml
header:
  title: This is the title
  subtitle: This is the subtitle
```

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

### Define country collection files

Source: https://lume.land/cms/fields/relation

Example file structure for a collection of countries.

```text
/en-spain.json
/pt-portugal.json
/fr-france.json
/it-italy.json
```

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

### Example Data Structure

Source: https://lume.land/cms/fields/choose-list

Represents the underlying data structure for a list of mixed object types.

```yaml
blocks:
  - type: title
    text: This is the title
  - type: content
    body: This is the content
```

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

### Define object list data structure

Source: https://lume.land/cms/fields/object-list

Example of a YAML structure representing a list of author objects.

```yaml
authors:
  - name: Óscar
    surname: Otero
  - name: Laura
    surname: Rubio
```

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

### Enable Git integration

Source: https://lume.land/cms/configuration/git

Initializes Git integration with default configuration settings.

```javascript
cms.git();
```

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

### Serve static files for customization

Source: https://lume.land/cms/configuration/options

Map URL prefixes to local folders to serve custom assets like CSS or JS files.

```typescript
const cms = lumeCMS({
  extraHead: '<link rel="stylesheet" href="/admin/custom/styles.css">',
  staticFolders: {
    custom: "./my-custom-stuff",
  },
});
```

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

### Configure collection with document labels

Source: https://lume.land/cms/fields/relation

Setting up a collection to extract labels and flags from filenames.

```javascript
cms.collection({
  name: "countries",
  documentLabel: (filename) => {
    const [code, name] = filename.replace(".json", "").split("-");
    return {
      label: name,
      flags: { code },
    };
  },
  // ...more options
});
```

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

### Configure Basic Authentication

Source: https://lume.land/cms/configuration/auth

Sets up simple username and password authentication for the CMS.

```javascript
cms.auth({
  user1: "password1",
  user2: "password2",
});

```

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

### Configure Basic Authentication with Environment Variables

Source: https://lume.land/cms/configuration/auth

Uses environment variables to define credentials, preventing hardcoded passwords in configuration files.

```javascript
const user = Deno.env.get("CMS_USERNAME");
const password = Deno.env.get("CMS_PASSWORD");

cms.auth({
  [user]: password,
});

```

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

### Configure upload folder with options

Source: https://lume.land/cms/configuration/uploads

Defines an upload folder using an object to specify name, description, and storage.

```javascript
cms.upload({
  name: "images",
  description: "Here you can manage all images of your posts",
  store: "src:images",
});
```

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

### Configure GitHub storage in Lume CMS

Source: https://lume.land/cms/configuration/storage

Initializes the GitHub storage adapter using a repository path and a personal access token.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import GitHub from "lume/cms/storage/github.ts";

const cms = lumeCMS();

const token = "xxx"; // A personal access token
const storage = GitHub.create("username/repo", token);

cms.storage("src", storage);

export default cms;
```

```typescript
GitHub.create("username/repo/path/to/root", token);
```

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

### Configure GitLab storage in Lume CMS

Source: https://lume.land/cms/configuration/storage

Initializes the GitLab storage adapter using a repository path and a personal access token.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import GitLab from "lume/cms/storage/gitlab.ts";

const cms = lumeCMS();

const token = "xxx"; // A personal access token
const storage = GitLab.create("username/repo", token);

cms.storage("src", storage);

export default cms;
```

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

### Configuring field options using site data

Source: https://lume.land/cms/fields

Access the site instance via the data object in the init function to populate field options dynamically.

```javascript
{
  name: "tags",
  type: "list",
  init(field, { data }) {
    const site = data.site;
    const allTags = site.search.values("tags");
    field.options = allTags;
  }
}
```

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

### Initialize LumeCMS instance

Source: https://lume.land/cms/configuration/options

Basic structure for initializing a LumeCMS instance with configuration options.

```typescript
import lumeCMS from "lume/cms/mod.ts";

const cms = lumeCMS({
  /* Options */
});
```

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

### Configure a preview URL

Source: https://lume.land/cms/configuration/collections

Sets a static preview URL for collections where items do not generate individual pages.

```javascript
cms.collection({
  name: "events",
  store: "src:_data/events/*.yml",
  fields: [
    "title: text",
    "date: datetime",
    "content: markdown",
  ],
  previewUrl: "/events/",
});
```

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

### Configure public path for uploads

Source: https://lume.land/cms/configuration/uploads

Maps source file locations to a different public URL path after site build.

```javascript
cms.upload({
  name: "images",
  store: "src:images",
  publicPath: "/",
});
```

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

### Register Deno KV Storage

Source: https://lume.land/cms/configuration/storage

Use Deno's built-in key-value database as a storage backend for LumeCMS.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import Kv from "lume/cms/storage/kv.ts";

const cms = lumeCMS();
const storage = await Kv.create();

cms.storage("src", storage);

export default cms;
```

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

### Configure Memory storage

Source: https://lume.land/cms/configuration/storage

Sets up an in-memory storage backend, primarily intended for testing purposes.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import Memory from "lume/cms/storage/memory.ts";

const cms = lumeCMS();

const storage = Memory.create();

cms.storage("src", storage);

export default cms;
```

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

### Define a document with positional arguments

Source: https://lume.land/cms/configuration/documents

Use the basic syntax to define a document by providing the name, storage path, and field definitions as arguments.

```javascript
cms.document("landing-page", "src:index.yml", [
  "title: text",
  "subtitle: text",
  "content: markdown",
]);
```

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

### Register File System Storage via String

Source: https://lume.land/cms/configuration/storage

Simplify file system storage registration by passing a folder name string directly.

```typescript
import lumeCMS from "lume/cms/mod.ts";

const cms = lumeCMS();

cms.storage("src", "files");

export default cms;
```

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

### Enable Unstable Deno KV API

Source: https://lume.land/cms/configuration/storage

Configure deno.json to enable the unstable KV API required for Deno.openKv().

```json
{
  "unstable": ["kv"]
}
```

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

### Configure SQLite storage

Source: https://lume.land/cms/configuration/storage

Initializes a SQLite database for Lume CMS storage using a file path.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import { Sqlite } from "lume/cms/storage/sqlite.ts";

const cms = lumeCMS();

cms.storage("db", Sqlite.create("my-database.db"));

export default cms;
```

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

### Configure GitHub storage in _cms.ts

Source: https://lume.land/cms/deployment/deno-deploy

Set up the CMS to use GitHub for storage instead of the local filesystem. Requires a GITHUB_TOKEN environment variable.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import GitHub from "lume/cms/storage/github.ts";
import { Octokit } from "npm:octokit";

const cms = lumeCMS();

cms.storage(
  "src",
  new GitHub({
    client: new Octokit({ auth: Deno.env.get("GITHUB_TOKEN") }),
    owner: "username",
    repo: "example",
  }),
);

// Rest of the configuration....

export default cms;
```

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

### Configure Git options

Source: https://lume.land/cms/configuration/git

Customizes Git integration settings such as the production branch name.

```javascript
cms.git({
  prodBranch: "master", // Change the production branch
});
```

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

### Default Upload Entity Usage

Source: https://lume.land/cms/fields/file

Demonstrates how the first registered upload entity is used by default when no specific upload is provided.

```javascript
// Register the "images" upload
cms.upload("images", "src:images");

cms.document("homepage", "src:index.yml", [
  "title: text",
  "content: markdown",
  "cover: file", // The `images` upload is used by default
]);
```

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

### Choose List Field Configuration

Source: https://lume.land/cms/fields/choose-list

Configuration object for defining a choose-list field with multiple object types.

```javascript
{
  name: "blocks",
  type: "choose-list",
  fields: [
    {
      name: "title",
      type: "object",
      fields: [
        "text: text"
      ]
    },
    {
      name: "content",
      type: "object",
      fields: [
        "body: markdown"
      ]
    },
  ]
}
```

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

### Configure site metadata

Source: https://lume.land/cms/configuration/options

Define site-wide information like name, description, and URL to be displayed on the CMS homepage.

```typescript
import lumeCMS from "lume/cms/mod.ts";

const cms = lumeCMS({
  site: {
    name: "My blog CMS",
    description: "Here I can edit the content of my blog",
    url: "https://myblog.com",
    body: `
    <p>Long text, for instructions or other content that you want to make it visible in the homepage</p>
    `,
  },
});
```

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

### Dynamically setting field values with init

Source: https://lume.land/cms/fields

The init function allows modifying field properties at runtime, such as setting a default value.

```javascript
{
  name: "password",
  type: "text",
  init(field) {
    field.value = generateRandomPassword();
  }
}
```

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

### Listen to Git events

Source: https://lume.land/cms/configuration/git

Registers an event listener to execute custom logic when a version is published.

```javascript
addEventListener("cms:versionPublished", (ev) => {
  const { name } = ev.details;

  console.log(`The version ${name} was published`);
});
```

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

### Defining fields with extra options

Source: https://lume.land/cms/fields

A collection of field definitions demonstrating various types and configuration attributes.

```javascript
[
  {
    name: "title",
    type: "text",
    label: "Title of the page",
    description: "It will be visible in the browser tab",
    attributes: {
      required: true,
      maxlength: 100,
    },
  },
  {
    name: "date",
    type: "datetime",
    label: "Created date",
    value: new Date(),
    description: "Set a future date if you want to publish it later",
    attributes: {
      placeholder: "For example: 2024-01-01 00:00:01",
    },
  },
  {
    name: "content",
    type: "markdown",
    label: "Page content",
    value: "Write **markdown** code here",
    description:
      `<a target="_blank" href="https://www.markdownguide.org">More info about markdown syntax</a>`,
  },
];
```

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

### Define a basic upload folder

Source: https://lume.land/cms/configuration/uploads

Registers an upload folder using a name and a storage path.

```javascript
cms.upload("images", "src:images");
```

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

### Configure Import Map for LumeCMS

Source: https://lume.land/cms

Add the Lume and LumeCMS entries to your import map to enable the library in your project.

```json
{
  "imports": {
    "lume/": "https://cdn.jsdelivr.net/gh/lumeland/lume@3.3.0/",
    "lume/cms/": "https://cdn.jsdelivr.net/gh/lumeland/cms@0.15.7/"
  }
}
```

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

### Configure list field with options

Source: https://lume.land/cms/fields/list

Adds a datalist of suggested values to the list field input.

```javascript
{
  name: "ingredients",
  type: "list",
  options: [
    "potatoes",
    "eggs",
    "salt",
  ]
}
```

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

### Implement a full custom field component

Source: https://lume.land/cms/fields/custom_fields

A complete implementation of a percentage field including DOM rendering, value retrieval, and state updates.

```javascript
customElements.define(
  "percentage-field",
  class extends Component {
    init() {
      // Get the field info
      const { schema, value, namePrefix, isNew } = this;

      // Generate the name of the input and the id
      const name = `${namePrefix}.${schema.name}`;
      const id = `field_${name}`;

      // Calculate the value of the input.
      // If `isNew` is true, we use schema.value as the default value.
      const val = isNew ? value ?? schema.value : value;

      // Print the HTML code
      this.innerHTML = `
      <label for="${id}">${schema.label}</label>
      <input id="${id}" type="number" value="${val}" min=0 max=100 name="${name}>
    `;
    }

    // Return the current value of this field
    get currentValue() {
      return this.querySelector("input").value;
    }

    // Update the field with a new state
    update(schema, value) {
      const input = this.querySelector("input");

      // Update the input value
      input.value = value ?? null;

      // Update the label value
      // since it could be changed from backend
      input.labels[0].innerHTML = schema.label;
    }
  },
);
```

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

### Implement Custom Login Form Provider

Source: https://lume.land/cms/configuration/auth

Replaces the default browser dialog with an HTML login form and session cookie management.

```javascript
cms.auth(
  { admin: { password: "secret" } },
  {
    init(options) {
      this.options = options;
    },
    login(request) {
      const cookie = request.headers.get("cookie") ?? "";
      const user = cookie.match(/session=([^;]+)/)?.[1];
      if (user && this.options.users.has(user)) return user;

      const basePath = this.options.basePath === "/"
        ? ""
        : this.options.basePath;
      return new Response(
        `<form method="POST" action="${basePath}/auth/login">
          <input name="user" placeholder="Username" />
          <input name="password" type="password" placeholder="Password" />
          <button>Login</button>
        </form>`,
        { headers: { "content-type": "text/html" } },
      );
    },
    async fetch(request) {
      const url = new URL(request.url);
      if (url.pathname.endsWith("/login") && request.method === "POST") {
        const data = await request.formData();
        const user = data.get("user");
        const password = data.get("password");
        const config = this.options.users.get(user);

        if (config && config.password === password) {
          return new Response(null, {
            status: 302,
            headers: {
              location: this.options.basePath,
              "set-cookie":
                `session=${user}; path=/; Secure; HttpOnly; SameSite=Strict`,
            },
          });
        }

        return new Response("Invalid credentials", { status: 401 });
      }
      return new Response("Not found", { status: 404 });
    },
    logout() {
      return new Response(null, {
        status: 302,
        headers: {
          location: this.options.basePath,
          "set-cookie": "session=; path=/; Secure; HttpOnly; Max-Age=0",
        },
      });
    },
  },
);

```

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

### Simplify field definitions with shorthand notation

Source: https://lume.land/cms/fields

Use the name:type string format for more concise field definitions.

```javascript
cms.document("happy-2024", "src:happy-2024.yml", [
  "title: text",
  "date: datetime",
  "content: markdown",
]);
```

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

### Configure a document in LumeCMS

Source: https://lume.land/cms/getting-started/edit-a-file

Define a document in the CMS by specifying its name, storage location, and input fields.

```typescript
import lumeCMS from "lume/cms/mod.ts";

const cms = lumeCMS();

cms.document("Homepage", "src:index.md", [
  "layout: hidden",
  "title: text",
  "description: textarea",
  "content: markdown",
]);

export default cms;
```

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

### Basic Select Field Configuration

Source: https://lume.land/cms/fields/select

Defines a simple select field with a list of string options.

```javascript
{
  name: "status",
  type: "select",
  options: [
    "enabled",
    "disabled",
    "unknown",
  ],
}
```

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

### Configure object-list field

Source: https://lume.land/cms/fields/object-list

Configuration object for defining an object-list field with specific sub-fields.

```javascript
{
  name: "authors",
  type: "object-list",
  fields: [
    "name: text",
    "surname: text",
  ]
}
```

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

### Define a document with an options object

Source: https://lume.land/cms/configuration/documents

Use an object to define document properties for better readability and access to additional configuration options.

```javascript
cms.document({
  name: "landing-page",
  store: "src:index.yml",
  fields: [
    "title: text",
    "subtitle: text",
    "content: markdown",
  ],
});
```

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

### Define a text field with datalist options

Source: https://lume.land/cms/fields/text

Provides a list of suggested values for the text input using the options property, which renders as a datalist.

```javascript
{
  name: "name",
  type: "text",
  options: [
    "Óscar",
    "Laura",
  ]
}
```

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

### Configure document type as object

Source: https://lume.land/cms/configuration/documents

Set the document type to object to store data as a single root object.

```javascript
cms.document({
  name: "notes",
  store: "src:notes.json",
  type: "object", // default value, no need to specify
  fields: [
    "title: text",
    "text: textarea",
  ],
});
```

```json
{
  "title": "Note title",
  "text": "This is the note"
}
```

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

### Customizing fields based on document data

Source: https://lume.land/cms/fields

Use the third argument of the init function to access the current document's data for conditional configuration.

```javascript
{
  name: "tags",
  type: "list",
  init(field, { data }, docData) {
    const site = data.site;

    // We are editing a document, so we can access to the data:
    if (docData) {
      const { lang } = docData

      const allTags = site.search.values(`tags lang=${lang}`);
      field.options = allTags;

    // It's a new document, we don't know the language yet.
    } else {
      const allTags = site.search.values("tags");
      field.options = allTags;
    }
  }
}
```

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

### Define preview URL mapping

Source: https://lume.land/cms/configuration/options

Provide a function to resolve file paths to their corresponding public preview URLs.

```typescript
const cms = lumeCMS({
  previewUrl(path: string) {
    if (path === "/index.md") return "/";
    if (path === "/about.md") return "/about/";
  }
});
```

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

### Define a basic collection

Source: https://lume.land/cms/configuration/collections

Defines a collection using positional arguments for name, storage path, and field definitions.

```javascript
cms.collection("posts", "src:posts/*.md", [
  "title: text",
  "content: markdown",
]);
```

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

### Create a custom element class

Source: https://lume.land/cms/fields/custom_fields

Extend the base Component class to define the custom element's behavior and initialization logic.

```javascript
import { Component } from "lume_cms/components/component.js";

customElements.define(
  "percentage-field",
  class extends Component {
    init() {
      // Here your code
    }
  },
);
```

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

### Saving Files in Document Directory

Source: https://lume.land/cms/fields/file

Using the {document_dirname} placeholder to store files in the same directory as the document.

```javascript
// Set an upload entity in `src:posts`
cms.upload("posts-images", "src:posts");

// Save the posts in the same directory (`src:posts`)
cms.collection({
  name: "posts",
  store: "src:posts/**/index.md",
  // Force a new folder per post
  documentName: "{title}/index.md",
  fields: [
    "title: text",
    "content: markdown",
    {
      name: "cover",
      type: "file",
      // Store the image in the same folder as the post
      upload: "posts-images:{document_dirname}",
    },
  ],
});
```

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

### Enable basic authentication in _cms.ts

Source: https://lume.land/cms/deployment/deno-deploy

Protect the CMS interface using basic authentication with credentials stored in environment variables.

```typescript
const username = Deno.env.get("USERNAME");
const password = Deno.env.get("PASSWORD");

const cms = lumeCMS({
  auth: {
    method: "basic",
    users: {
      [username]: password,
    },
  },
});
```

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

### Basic File Field Configuration

Source: https://lume.land/cms/fields/file

A standard file field definition using the uploads option.

```javascript
{
  name: "image",
  type: "file",
  uploads: "uploads",
}
```

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

### Register File System Storage

Source: https://lume.land/cms/configuration/storage

Explicitly register a file system storage using the Fs class and a path.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import Fs from "lume/cms/storage/fs.ts";

const cms = lumeCMS();
const storage = Fs.create(Deno.cwd() + "/files");

cms.storage("src", storage);

export default cms;
```

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

### Configure document type as object-list

Source: https://lume.land/cms/configuration/documents

Set the document type to object-list to store data as an array of objects.

```javascript
cms.document({
  name: "notes",
  store: "src:notes.json",
  type: "object-list",
  fields: [
    "title: text",
    "text: textarea",
  ],
});
```

```json
[
  {
    "title": "First note",
    "text": "Text of the first note"
  },
  {
    "title": "Second note",
    "text": "Text of the second note"
  }
]
```

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

### Define Custom AuthProvider Interface

Source: https://lume.land/cms/configuration/auth

Outlines the required methods for implementing a custom authentication provider.

```typescript
interface AuthProvider {
  /** Called once on startup with the user map and base path */
  init(
    options: { basePath: string; users: Map<string, UserConfiguration> },
  ): void;

  /** Called on every request. Return the matched username on success,
   *  or a Response (e.g. a challenge or redirect) to deny access. */
  login(request: Request): Response | string | Promise<Response | string>;

  /** Called when the user triggers the logout action */
  logout(request: Request): Response | Promise<Response>;

  /** Handles requests under the /auth/* path (e.g. form submissions or OAuth callbacks) */
  fetch(request: Request): Response | Promise<Response>;
}

```

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

### Define a list field

Source: https://lume.land/cms/fields/list

Basic configuration for a list field to manage string elements.

```javascript
{
  name: "ingredients",
  type: "list",
}
```

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

### Define a Collection in LumeCMS

Source: https://lume.land/cms/getting-started/collections

Configures a collection named 'Posts' that maps to Markdown files in the src/posts directory with specific fields.

```javascript
cms.collection("Posts", "src:posts/*.md", [
  "title: text",
  "author: text",
  "tags: list",
  "content: markdown",
]);
```

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

### Assign fields to a view

Source: https://lume.land/cms/configuration/views

Use the view option within a field definition to group it under a specific view name.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    {
      name: "title",
      type: "text",
    },
    {
      name: "published",
      type: "datetime",
      view: "editor",
    },
    {
      name: "draft",
      type: "checkbox",
      view: "editor",
    },
    {
      name: "content",
      type: "markdown",
    },
  ],
});
```

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

### Configure LumeCMS document fields

Source: https://lume.land/cms/fields

Define document fields using an array of objects specifying name and type.

```javascript
cms.document("happy-2024", "src:happy-2024.yml", [
  {
    name: "title",
    type: "text",
  },
  {
    name: "date",
    type: "datetime",
  },
  {
    name: "content",
    type: "markdown",
  },
]);
```

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

### Define a collection with an options object

Source: https://lume.land/cms/configuration/collections

Uses an object to define collection properties, providing more flexibility than positional arguments.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text",
    "content: markdown",
  ],
});
```

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

### Basic Markdown Field Configuration

Source: https://lume.land/cms/fields/markdown

Defines a standard markdown field for storing content.

```javascript
{
  name: "content",
  type: "markdown",
}
```

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

### Basic Datetime Field Configuration

Source: https://lume.land/cms/fields/datetime

Defines a standard datetime field for storing date values.

```javascript
{
  name: "published",
  type: "datetime",
}
```

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

### Define a URL field

Source: https://lume.land/cms/fields/url

Basic configuration for a URL field within a schema definition.

```javascript
{
  name: "href",
  type: "url",
}
```

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

### Basic Radio Field Configuration

Source: https://lume.land/cms/fields/radio

Defines a radio field with a simple array of string options.

```javascript
{
  name: "status",
  type: "radio",
  options: [
    "enabled",
    "disabled",
    "unknown",
  ],
}
```

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

### Basic rich-text field configuration

Source: https://lume.land/cms/fields/rich-text

Define a standard rich-text field within the schema.

```javascript
{
  name: "content",
  type: "rich-text",
}
```

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

### Set a custom label for uploads

Source: https://lume.land/cms/configuration/uploads

Defines a visible label for the upload menu item, defaulting to the name if omitted.

```javascript
cms.upload({
  name: "images",
  label: "Posts' images",
  description: "Here you can manage all images of your posts",
  store: "src:images",
});
```

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

### Rich-text field with upload and relative path options

Source: https://lume.land/cms/fields/rich-text

Configure the field to support file uploads and store links as relative paths.

```javascript
{
  name: "content",
  type: "rich-text",
  upload: "images",
  relativePath: true
}
```

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

### Add a description to a document

Source: https://lume.land/cms/configuration/documents

Include a description field to display helpful text below the document name in the CMS.

```javascript
cms.document({
  name: "landing-page",
  description: "Edit the content of the landing page",
  store: "src:index.yml",
  fields: [
    "title: text",
    "subtitle: text",
    "content: markdown",
  ],
});
```

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

### Define a textarea field configuration

Source: https://lume.land/cms/fields/textarea

Configures a textarea field with a name and a maximum character length attribute.

```javascript
{
  name: "description",
  type: "textarea",
  attributes: {
    maxlength: 1500
  }
}
```

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

### Define an upload directory in LumeCMS

Source: https://lume.land/cms/getting-started/uploads

Use the cms.upload function to specify a folder for storing uploaded files. The first argument is the display name, and the second is the source path.

```javascript
cms.upload("Files", "src:files");
```

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

### Set default visible views

Source: https://lume.land/cms/configuration/views

Configure the views option in the collection to define which views are visible by default in the interface.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  views: ["editor"],
  fields: [
    {
      name: "title",
      type: "text",
    },
    {
      name: "published",
      type: "datetime",
      view: "editor",
    },
    {
      name: "draft",
      type: "checkbox",
      view: "editor",
    },
    {
      name: "content",
      type: "markdown",
    },
  ],
});
```

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

### Customize document labels

Source: https://lume.land/cms/configuration/collections

Provides a function to format how document names appear in the collection list.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text!",
    "author: text!",
    "content: markdown",
  ],
  documentLabel(name) {
    return name.replace(".md", "");
  },
});
```

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

### Set a custom label for a document

Source: https://lume.land/cms/configuration/documents

Define a label to change the display name of the document in the CMS menu.

```javascript
cms.document({
  name: "landing-page",
  label: "This is your homepage",
  description: "Edit the content of the home page",
  store: "src:index.yml",
  fields: [
    "title: text",
    "subtitle: text",
    "content: markdown",
  ],
});
```

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

### Select Field with Label-Value Pairs

Source: https://lume.land/cms/fields/select

Configures a select field using objects to provide distinct labels and values for options.

```javascript
{
  name: "status",
  type: "select",
  options: [
    "enabled",
    "disabled",
    {
      label: "Not known",
      value: "unknown"
    },
  ],
}
```

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

### Define an object field

Source: https://lume.land/cms/fields/object

Configuration for an object field containing title and subtitle fields.

```javascript
{
  name: "header",
  type: "object",
  fields: [
    "title: string",
    "subtitle: string",
  ],
}
```

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

### Datetime Field with Default Value

Source: https://lume.land/cms/fields/datetime

Uses the init function to automatically set the field value to the current date and time upon document creation.

```javascript
{
  name: "created_at",
  type: "datetime",
  init(field) {
    field.value = new Date();
  }
}
```

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

### Add a description to a collection

Source: https://lume.land/cms/configuration/collections

Displays a description string below the collection name in the CMS interface.

```javascript
cms.collection({
  name: "posts",
  description: "To create, edit or delete the posts of the blog",
  store: "src:posts/*.md",
  fields: [
    "title: text",
    "content: markdown",
  ],
});
```

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

### Define a relation-list field

Source: https://lume.land/cms/fields/relation-list

Configures a field to select multiple users from the 'users' collection with a custom label and value mapping.

```javascript
{
  name: "user",
  type: "relation-list",
  collection: "users",
  option: ({ label, flags }) => ({ label, value: flags.id })
}
```

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

### Configure automatic document renaming

Source: https://lume.land/cms/configuration/collections

Sets the rename option to 'auto' to update the filename dynamically based on document field changes.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text!",
    "author: text!",
    "content: markdown",
  ],
  documentName(data) {
    return `${data.title}-${data.author}.md`;
  },

  // Don't allow the user to edit the document name
  // and update it everytime the title or author changes.
  rename: "auto",
});
```

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

### Markdown Field with Relative Path Option

Source: https://lume.land/cms/fields/markdown

Enables relative path storage for uploaded files within the markdown content.

```javascript
{
  name: "content",
  type: "markdown",
  upload: "images",
  relativePath: true
}
```

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

### Generate document names automatically

Source: https://lume.land/cms/configuration/collections

Uses field values to construct the filename for new documents. Supports both string patterns and custom functions.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text!",
    "content: markdown",
  ],
  documentName: "{title}.md",
});
```

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text!",
    "author: text!",
    "content: markdown",
  ],
  documentName(data) {
    return `${data.title}-${data.author}.md`;
  },
});
```

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

### Configure Codeberg storage

Source: https://lume.land/cms/configuration/storage

Connects Lume CMS to a Codeberg repository using a personal access token.

```typescript
import lumeCMS from "lume/cms/mod.ts";
import Codeberg from "lume/cms/storage/codeberg.ts";

const cms = lumeCMS();

const token = "xxx"; // A personal access token
const storage = Codeberg.create("username/repo", token);

cms.storage("src", storage);

export default cms;
```

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

### Storing Relative Paths

Source: https://lume.land/cms/fields/file

Enabling relativePath to store file paths relative to the document for better portability.

```javascript
// Set an upload entity in `src:posts`
cms.upload("posts-images", "src:posts");

// Save the posts in the same directory (`src:posts`)
cms.collection({
  name: "posts",
  store: "src:posts/**/index.md",
  // Force a new folder per post
  documentName: "{title}/index.md",
  fields: [
    "title: text",
    "content: markdown",
    {
      name: "cover",
      type: "file",
      // Store the image in the same folder as the post
      upload: "posts-images:{document_dirname}",
      // The value written for "cover" would be something like "./my-image.jpg",
      // instead of "/files/posts/my-article/my-image.jpg"
      relativePath: true,
    },
  ],
});
```

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

### Define a color field

Source: https://lume.land/cms/fields/color

Basic configuration for a color field within a schema definition.

```javascript
{
  name: "background_color",
  type: "color",
}
```

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

### Define a current-datetime field

Source: https://lume.land/cms/fields/current-datetime

Basic configuration for a field that tracks the last modification time.

```javascript
{
  name: "last_modified",
  type: "current-datetime",
}
```

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

### Define a basic text field

Source: https://lume.land/cms/fields/text

Configures a standard text input with validation attributes like required and maxlength.

```javascript
{
  name: "title",
  type: "text",
  attributes: {
    required: true,
    maxlength: 200
  }
}
```

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

### Set a custom label for a collection

Source: https://lume.land/cms/configuration/collections

Defines a custom display name for the collection in the menu.

```javascript
cms.collection({
  name: "posts",
  label: "Your posts!",
  description: "To create, edit or delete the posts of the blog",
  store: "src:posts/*.md",
  fields: [
    "title: text",
    "content: markdown",
  ],
});
```

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

### Define a custom percentage field component

Source: https://lume.land/cms/fields/custom_fields

Uses the dom module to generate label and input elements for a custom field component. The component manages its own state and updates via the update method.

```javascript
import { Component } from "lume_cms/components/component.js";
import dom from "dom";

customElements.define(
  "percentage-field",
  class extends Component {
    init() {
      // Get the field info
      const { schema, value, namePrefix, isNew } = this;

      // Generate the name of the input and the id
      const name = `${namePrefix}.${schema.name}`;
      const id = `field_${name}`;

      // Append the <label> to this
      dom("label", { for: id, html: schema.label }, this);

      // Append the <input> to this
      // and save the element in this.input to reuse later.
      this.input = dom("input", {
        type: "number",
        name,
        value: isNew ? value ?? schema.value : value,
        id,
        min: 0,
        max: 100,
      }, this);
    }

    // Return the current value of this field
    get currentValue() {
      return this.input.value;
    }

    // Update the field with a new state
    update(schema, value) {
      // Update the input value
      this.input.value = value ?? null;

      // Update the label value
      // since it could be changed from backend
      this.input.labels[0].innerHTML = schema.label;
    }
  },
);
```

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

### Define a number field

Source: https://lume.land/cms/fields/number

Basic configuration for a field of type number.

```javascript
{
  name: "position",
  type: "number",
}
```

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

### Define a relation field

Source: https://lume.land/cms/fields/relation

Basic configuration for a relation field pointing to a specific collection.

```javascript
{
  name: "user",
  type: "relation",
  collection: "users",
  option: ({ label, flags }) => ({ label, value: flags.id })
}
```

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

### Define a date field

Source: https://lume.land/cms/fields/date

Basic configuration for a date field within the CMS schema.

```javascript
{
  name: "published",
  type: "date",
}
```

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

### Define a custom field with cms.field

Source: https://lume.land/cms/fields/custom_fields

Register a new field type by providing a tag, import URL, and data transformation logic.

```javascript
cms.field("percentage", {
  tag: "percentage-field",
  jsImport: "https://example.com/custom-fields/percentage-field.js",
  applyChanges(data, changes, field) {
    const { name } = field;
    const value = changes[name];
    data[name] value ? Number(value) : undefined;
  },
});
```

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

### Define required fields using shorthand

Source: https://lume.land/cms/fields

Append an exclamation mark to the type in the shorthand notation to mark a field as required.

```javascript
cms.document("happy-2024", "src:happy-2024.yml", [
  "title: text!", // This value is required
  "date: datetime",
  "content: markdown",
]);
```

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

### Define source path mapping

Source: https://lume.land/cms/configuration/options

Provide a function to resolve public URLs back to their source file paths for editing.

```typescript
const cms = lumeCMS({
  sourcePath(url: string) {
    if (url === "/") return "/index.md";
    if (url === "/about/") return "/about.md";
  }
});
```

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

### Markdown Field with Upload Configuration

Source: https://lume.land/cms/fields/markdown

Configures file upload settings for the markdown field, either by specifying an entity name or disabling the feature.

```javascript
{
  name: "content",
  type: "markdown",
  upload: "images"
}
```

```javascript
{
  name: "content",
  type: "markdown",
  upload: false
}
```

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

### Markdown Field with Custom Snippets

Source: https://lume.land/cms/fields/markdown

Adds custom snippets to the editor, supporting the {$ placeholder for selected text.

```javascript
{
  name: "content",
  type: "markdown",
  snippets: [
    {
      label: "copyright",
      value: "© Acme Inc, 2025"
    },
    {
      label: "Keyboard input",
      value: "<kbd>{$}</kbd>"
    },
  ]
}
```

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

### Define a SQLite collection

Source: https://lume.land/cms/configuration/storage

Registers a collection in SQLite, specifying the table name and the field used for listing elements.

```javascript
cms.collection({
  name: "posts",
  store: "db:posts(title)",
  fields: [...]
});
```

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

### Define a time field

Source: https://lume.land/cms/fields/time

Basic configuration for a time field in the CMS schema.

```javascript
{
  name: "starts_at",
  type: "time",
}
```

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

### File Field with Specific Upload Entity

Source: https://lume.land/cms/fields/file

Configuring a file field to use a specific upload entity and subdirectory.

```javascript
{
  name: "image",
  type: "file",
  upload: "images:posts"
}
```

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

### Define a checkbox field

Source: https://lume.land/cms/fields/checkbox

Basic configuration for a checkbox field named draft.

```javascript
{
  name: "draft",
  type: "checkbox",
}
```

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

### Use relation field in a collection

Source: https://lume.land/cms/fields/relation

Implementing the relation field to reference the countries collection.

```javascript
cms.collection({
  name: "users",
  store: "src:users/*.md",
  fields: [
    "name: text",
    {
      name: "country",
      type: "relation",
      collection: "countries",
      option: ({ label, flags }) => { label, value: flags.code }
    }
  ]
});
```

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

### Define dynamic collection views

Source: https://lume.land/cms/configuration/collections

Uses a function for the views property to conditionally show fields based on whether a document is being created or edited.

```javascript
cms.collection({
  name: "countries",
  store: "src:countries/*.yml",
  views(data) {
    if (data) {
      // Editing document, show the full view
      return ["full"];
    }
  },
  fields: [
    "title: text",
    {
      type: "markdown",
      name: "content",
      view: "full", // This field is only visible if the "full" view is active
    },
  ],
  create: false,
  delete: false,
});
```

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

### Define a code field

Source: https://lume.land/cms/fields/code

Basic configuration for adding a code field to the CMS schema.

```javascript
{
  name: "content",
  type: "code",
}
```

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

### Disable create, edit, and delete actions

Source: https://lume.land/cms/configuration/collections

Restricts user actions on a collection by setting create, edit, and delete flags to false.

```javascript
cms.collection({
  name: "countries",
  store: "src:countries/*.yml",
  fields: [
    "title: text",
    "content: markdown",
  ],
  // Don't allow the user to create, edit or delete countries
  create: false,
  delete: false,
  edit: false,
});
```

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

### Define an email field

Source: https://lume.land/cms/fields/email

Basic configuration for an email field within the CMS schema.

```javascript
{
  name: "contact",
  type: "email",
}
```

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

### Radio Field Configuration

Source: https://lume.land/cms/fields/radio

Configuration schema for the radio field type, including the required options list.

```APIDOC
## Radio Field Configuration

### Description
The `radio` field type is used to store a single selection from a list of available options. It renders as a set of `<input type="radio">` elements.

### Configuration Object
- **name** (string) - Required - The identifier for the field.
- **type** (string) - Required - Must be set to "radio".
- **options** (array) - Required - A list of available options. Each item can be a string or an object with `label` and `value` properties.

### Example
```json
{
  "name": "status",
  "type": "radio",
  "options": [
    "enabled",
    "disabled",
    {
      "label": "Not known",
      "value": "unknown"
    }
  ]
}
```
```

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

### Highlighting elements with cssSelector

Source: https://lume.land/cms/fields

Use cssSelector to link a field to a specific DOM element in the preview pane.

```javascript
{
  type: "text",
  name: "title",
  cssSelector: "h1.title"
}
```

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

### Define a read-only current-datetime field

Source: https://lume.land/cms/fields/current-datetime

Configuration to prevent user modification of the automatically updated datetime field.

```javascript
{
  name: "last_modified",
  type: "current-datetime",
  attributes: {
    readonly: true
  }
}
```

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

### Hide upload entry from homepage

Source: https://lume.land/cms/configuration/uploads

Prevents the upload folder from appearing in the CMS main menu by setting listed to false.

```javascript
cms.upload({
  name: "images",
  store: "src:images",
  listed: false, // Hide from the main menu.
});
```

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

### Radio Field with Labelled Options

Source: https://lume.land/cms/fields/radio

Defines a radio field where options can be objects containing both a label and a value.

```javascript
{
  name: "status",
  type: "radio",
  options: [
    "enabled",
    "disabled",
    {
      label: "Not known",
      value: "unknown"
    },
  ],
}
```

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

### Inject custom HTML via extraHead

Source: https://lume.land/cms/configuration/options

Use extraHead to inject custom CSS or HTML into the CMS interface.

```typescript
const cms = lumeCMS({
  extraHead: `
<style>
  body {
    color: pink;
  }
</style>
  `,
});
```

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

### Transform data before saving

Source: https://lume.land/cms/configuration/collections

Uses a transform function to modify data values, such as formatting strings, before they are persisted.

```javascript
cms.collection({
  name: "posts",
  store: "src:posts/*.md",
  fields: [
    "title: text!",
    "author: text!",
    "content: markdown",
  ],
  transform(data, cmsContent, isNew) {
    if (isNew) {
      // Convert the title to uppercase when a document is created
      data.title = data.title.toUpperCase();
    }
  },
});
```

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

### Transforming field values

Source: https://lume.land/cms/fields

The transform function allows modifying the input value before it is saved to the data store.

```javascript
{
  name: "code",
  type: "text",
  transform(value) {
    return value?.toUpperCase(); // Ensure the value is stored always in uppper case.
  }
}
```

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

### Define a hidden field

Source: https://lume.land/cms/fields/hidden

Use this configuration to store a value that remains invisible in the user interface.

```javascript
{
  name: "layout",
  type: "hidden",
  value: "layouts/base.vto",
}
```

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

### Disable document editing

Source: https://lume.land/cms/configuration/documents

Set the edit option to false to prevent modifications to the document content.

```javascript
cms.document({
  name: "landing-page",
  store: "src:index.yml",
  fields: [
    "title: text",
    "subtitle: text",
    "content: markdown",
  ],
  edit: false,
});
```

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

### Restrict upload file operations

Source: https://lume.land/cms/configuration/uploads

Disables specific file management actions like creation, editing, renaming, or deletion.

```javascript
cms.upload({
  name: "images",
  store: "src:images",
  // Don't allow the user to create, edit, rename or delete images
  create: false,
  delete: false,
  edit: false,
  rename: false,
});
```
Tokens:
Raw