Project Configuration

Every repository managed by Sitepins carries a configuration file at .sitepins/config.json. This file informs the CMS where content, media, and configuration files live, and defines how files should be organized in the editor sidebar.

The `.sitepins/config.json` Specification

Below is an annotated example of a production .sitepins/config.json:


{
  "content": "src/content",
  "media": "public/images",
  "public": "public",
  "configs": [
    "src/config/site.json",
    "astro.config.mjs"
  ],
  "arrangement": [
    {
      "id": "blog-folder",
      "type": "folder",
      "groupName": "Blog Posts",
      "targetPath": "blog",
      "include": ["**/*.md", "**/*.mdx"],
      "exclude": ["**/_drafts/**"]
    },
    {
      "id": "homepage-heading",
      "type": "heading",
      "groupName": "Landing Pages"
    },
    {
      "id": "home-file",
      "type": "file",
      "groupName": "Landing Pages",
      "targetPath": "homepage/index.md"
    }
  ],
  "customCommit": true
}

Field Definitions

Field	Type	Required	Description
`content`	`string`	Yes	Path to the content root directory relative to the repository root (e.g. `src/content` or `content`).
`media`	`string`	Yes	Path to the primary media upload directory (e.g. `public/images` or `static/uploads`).
`public`	`string`	Yes	Public static root folder (e.g. `public` or `static`). Used to resolve relative image paths in previews.
`configs`	`string[]`	No	List of configuration files exposed for editing in the code editor (e.g. `site.json`, `theme.yaml`).
`arrangement`	`Array`	No	Custom grouping and sorting rules for the editor sidebar (see below).
`customCommit`	`boolean`	No	When `true`, prompts editors to provide custom Git commit messages when saving changes. Defaults to `false`.

Sidebar Arrangement Rules

By default, Sitepins mirrors the physical folder hierarchy of your content root. The arrangement array allows you to restructure and group files in the UI without altering repository file paths.

1. Folder Arrangement (`type: "folder"`)

Collects and groups files from a subfolder into a named sidebar category:


{
  "id": "docs-group",
  "type": "folder",
  "groupName": "Documentation",
  "targetPath": "docs",
  "include": ["**/*.{md,mdx}"],
  "exclude": ["**/archive/**"]
}

targetPath: Relative path inside your content folder.
include / exclude: Glob patterns for filtering matching files.

2. Section Heading (`type: "heading"`)

Creates a non-clickable section separator in the sidebar:


{
  "id": "legal-heading",
  "type": "heading",
  "groupName": "Legal Documents"
}

3. Pinning Specific Files (`type: "file"`)

Pins an individual file under a specific category:


{
  "id": "privacy-policy",
  "type": "file",
  "groupName": "Legal Documents",
  "targetPath": "legal/privacy.md"
}

Automated Format Migration

Older versions of Sitepins stored configurations in a nested format:


// Legacy format (deprecated)
{
  "content": { "root": "src/content" },
  "media": { "root": "public/images", "public": "public" },
  "showCommitModal": true
}

Sitepins automatically normalizes legacy configurations on load:

When you open a project, Sitepins inspects .sitepins/config.json.
If legacy keys are detected, the configuration is automatically transformed into the current flat format.
Sitepins commits the updated .sitepins/config.json back to your Git repository with the commit message:
```
chore: migrate config to new format
```
This ensures that projects stay up to date without requiring manual file edits.

Runtime Config vs. Persisted Config

The full running configuration in the Redux store combines .sitepins/config.json with temporary session state:

Setting	Persisted to Git?	Purpose
`content`, `media`, `configs`	Yes	Repository paths.
`arrangement`, `customCommit`	Yes	UI display preferences.
`provider`, `owner`, `repoName`, `branch`	No	Active Git repository coordinates.
`token`, `refreshToken`	No	Ephemeral Git provider session credentials.
`isRawMode`, `fullscreen`	No	Local editor display state.

Sitepins never writes access tokens, personal secrets, or session data into .sitepins/config.json. Only repository layout settings are committed to Git.