Content schemas define the structure and fields for your content files, making it easy to create consistent, well-structured content across your site. With schemas, you can define templates that automatically populate new files with the correct frontmatter fields and default values.

What are Schemas?

A schema is a template that defines:

• The fields that should appear in your content files
• The type of each field (text, number, date, boolean, etc.)
• Default values for fields
• Whether fields are required or optional
• Field labels and descriptions

When you create a new content file in a folder with a schema, Sitepins automatically generates the file with all the defined fields, saving you time and ensuring consistency.

---

Creating a Schema

From a Content Folder

1. Navigate to any content folder in your project
2. Click “Create Schema To Add New File” button
3. In the schema dialog, select an existing file to use as a template
4. Sitepins will automatically analyze the file and extract its frontmatter fields

Schema Generation Process

When you select a file, Sitepins:

• Parses the frontmatter (YAML or TOML)
• Detects field types automatically
• Extracts default values
• Creates a schema template you can customize

---

Schema Fields

Each field in your schema can have the following properties:

Field Name

The key used in the frontmatter (e.g., title, date, author)

Field Type

Sitepins supports various field types:

• Text - Single-line text input
• Textarea - Multi-line text input
• Number - Numeric values
• Boolean - True/false toggle
• Date - Date picker
• Datetime - Date and time picker
• Select - Dropdown with predefined options
• Array - List of values
• Object - Nested fields

Default Value

The value automatically populated when creating new content

Required

Whether the field must be filled in before saving

Label

Display name shown in the editor

Description

Help text explaining what the field is for

---

Adding Fields to a Schema

After creating a schema, you can add more fields:

1. Click the “Add Field” button at the bottom of the schema editor
2. Fill in the field properties:
   • Name - The field key
   • Type - Select from available field types
   • Label - Display name
   • Default Value - Optional default
   • Required - Toggle if mandatory
3. Click “Add” to save the field

---

Editing Fields

To modify an existing field:

1. Find the field in the schema editor
2. Click to expand the field settings
3. Update any properties (type, label, default value, etc.)
4. Changes are saved when you update the schema

---

Deleting Fields

To remove a field from a schema:

1. Find the field in the schema editor
2. Click the delete icon (trash can)
3. The field will be removed from the template

---

Schema Inheritance

Sitepins supports schema inheritance for nested folder structures:

How It Works

If a subfolder doesn’t have its own schema, Sitepins automatically searches parent folders for an applicable schema.

Example:

.sitepins/schema/blog.json  ← Schema for blog folder

content/
  blog/
    2024/
      post-1.md  ← Uses blog schema
      post-2.md  ← Uses blog schema

Even though the 2024 folder doesn’t have its own schema, new files created there will use the parent blog schema.

Benefits

• Define schemas once for entire content sections
• Maintain consistency across nested folders
• Reduce schema duplication

---

Managing Schemas

Schema Management Page

Access all your schemas from the project settings:

1. Go to your project dashboard
2. Navigate to Schema Management
3. View all schemas in your project

Schema List View

The schema management page shows:

• Schema Name - The display name
• File Path - Location in .sitepins/schema/
• Field Count - Number of fields in the schema

Editing Schemas

From the schema list:

1. Click “Edit Schema” on any schema
2. Modify fields, add new ones, or delete existing fields
3. Click “Update Schema” to save changes

Deleting Schemas

To remove a schema:

1. Open the schema in edit mode
2. Click “Delete Schema” button
3. Confirm the deletion

---

File Types and Frontmatter Formats

Schemas support different file types and frontmatter formats:

Supported File Types

• Markdown (.md)
• MDX (.mdx)

Supported Frontmatter Formats

• YAML - Uses --- delimiters
• TOML - Uses +++ delimiters

Sitepins automatically detects the format from your template file and uses it for all new files created with that schema.

---

Best Practices

1. Start with an Existing File

Use a well-structured existing file as your schema template. This ensures you capture all necessary fields and their correct types.

2. Use Descriptive Labels

Give fields clear, descriptive labels so content editors understand what each field is for.

3. Set Sensible Defaults

Provide default values for fields that commonly have the same value (e.g., draft: true for new posts).

4. Mark Required Fields

Use the required flag for essential fields like title or date to prevent incomplete content.

5. Organize with Schemas

Create separate schemas for different content types (blog posts, documentation pages, product pages, etc.).

6. Use Schema Inheritance

For nested folder structures, create schemas at the top level and let subfolders inherit them.

---

Example Schema

Here’s what a blog post schema might look like:

{
  "name": "Blog Post",
  "file": "content/blog/example-post.md",
  "fileType": "md",
  "fmType": "yaml",
  "template": [
    {
      "name": "title",
      "type": "text",
      "label": "Post Title",
      "required": true
    },
    {
      "name": "date",
      "type": "datetime",
      "label": "Publish Date",
      "required": true
    },
    {
      "name": "author",
      "type": "text",
      "label": "Author Name",
      "default": "John Doe"
    },
    {
      "name": "draft",
      "type": "boolean",
      "label": "Draft Status",
      "default": true
    },
    {
      "name": "tags",
      "type": "array",
      "label": "Tags",
      "default": []
    }
  ]
}

---

Troubleshooting

Schema Not Appearing

If your schema isn’t being used:

• Check that the schema file exists in .sitepins/schema/
• Verify the schema name matches the folder structure
• Try refreshing the page

Fields Not Showing Correctly

If fields aren’t displaying as expected:

• Verify the field type is correct
• Check for typos in field names
• Ensure the frontmatter format matches the schema

Can’t Create New Files

If you can’t create new files in a folder:

• Make sure a schema exists for that folder or a parent folder
• Check that the schema has valid fields
• Verify you have write access to the repository

---

Need Help?

• Join our Discord Community
• Contact Support
• Check the GitHub Discussions