{ "version": "https://jsonfeed.org/version/1", "title": "Marmite 0.4.1", "home_page_url": "https://marmite.blog", "feed_url": "https://marmite.blog/tag-api.json", "description": "Static Site Generator
for blogs
made with ❤️ and 🦀", "items": [ { "id": "https://marmite.blog/content-management-api.html", "url": "https://marmite.blog/content-management-api.html", "title": "Content Management API", "content_html": "

When you run marmite with --serve, the built-in server exposes a REST API under /__marmite__/ for managing content and configuration programmatically. This API is used by the marmite-toolbar and can also be called directly with curl or any HTTP client.

\n
\n

Important

\n

The API is only available on the local dev server (--serve). It is not part of the generated static site and is not exposed in production deployments.

\n
\n

Endpoints

\n

Content

\n

Create content

\n
POST /__marmite__/content\n
\n

Creates a new markdown file in the content directory.

\n

Request body (JSON):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
titlestringyesContent title
tagsstring or arraynoComma-separated string or array of tags
pagebooleannoIf true, creates a page (no date). Default: false
langstringnoISO 639-1 language code
translatesstringnoSlug of the content this translates
directorystringnoSubdirectory within the content folder
\n

Example:

\n
$ curl -X POST http://localhost:8000/__marmite__/content \\\n  -H 'Content-Type: application/json' \\\n  -d '{"title": "Getting Started with Rust", "tags": "rust, tutorial"}'\n
\n

Response (201):

\n
{\n  "file": "content/posts/getting-started-with-rust.md",\n  "title": "Getting Started with Rust",\n  "slug": "getting-started-with-rust",\n  "is_page": false,\n  "date": "2026-07-09 12:00:00",\n  "tags": "rust, tutorial"\n}
\n

Update frontmatter

\n
PATCH /__marmite__/content/{slug}\n
\n

Updates frontmatter fields of an existing content file. The markdown body is preserved. Set a field to null to remove it.

\n

Example:

\n
$ curl -X PATCH http://localhost:8000/__marmite__/content/my-post \\\n  -H 'Content-Type: application/json' \\\n  -d '{"tags": "rust, web", "stream": "tutorial", "pinned": true}'\n
\n

Response (200):

\n
{\n  "slug": "my-post",\n  "file": "content/posts/my-post.md",\n  "frontmatter": {\n    "title": "My Post",\n    "tags": "rust, web",\n    "stream": "tutorial",\n    "pinned": true\n  }\n}
\n

Clone content

\n
POST /__marmite__/content/{slug}/clone\n
\n

Copies the entire file (frontmatter and markdown body) to a new file with a different title and slug. The aliases and translates fields are removed from the clone.

\n

Request body (JSON):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
titlestringyesTitle for the cloned content
slugstringnoCustom slug. If omitted, derived from the title
\n

Example:

\n
$ curl -X POST http://localhost:8000/__marmite__/content/my-post/clone \\\n  -H 'Content-Type: application/json' \\\n  -d '{"title": "My Post (Copy)"}'\n
\n

Response (201):

\n
{\n  "slug": "my-post-copy",\n  "file": "content/posts/my-post-copy.md",\n  "source": "my-post"\n}
\n

Move / Rename content

\n
POST /__marmite__/content/{slug}/move\n
\n

Moves or renames a content file. The filename must end with .md. Paths with / are relative to the content directory and intermediate directories are created automatically.

\n

Request body (JSON):

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
filenamestringyesNew filename or path (e.g. new-name.md or posts/new-name.md)
\n

Example:

\n
$ curl -X POST http://localhost:8000/__marmite__/content/my-post/move \\\n  -H 'Content-Type: application/json' \\\n  -d '{"filename": "tutorials/my-post.md"}'\n
\n

Response (200):

\n
{\n  "slug": "my-post",\n  "old_file": "content/posts/my-post.md",\n  "new_file": "content/tutorials/my-post.md"\n}
\n
\n

The response slug reflects the actual slug the content will render as. If the file has an explicit slug: in frontmatter, that value is returned regardless of the new filename.

\n
\n

Delete content

\n
DELETE /__marmite__/content/{slug}\n
\n

Deletes the markdown file associated with the given slug.

\n

Example:

\n
$ curl -X DELETE http://localhost:8000/__marmite__/content/my-post\n
\n

Response (200):

\n
{\n  "slug": "my-post",\n  "file": "content/posts/my-post.md",\n  "deleted": true\n}
\n

Configuration

\n

Create config

\n
POST /__marmite__/config\n
\n

Creates a new marmite.yaml with default values. Returns 409 if the file already exists.

\n

Update config

\n
PATCH /__marmite__/config\n
\n

Merges fields into the existing marmite.yaml. Set a field to null to remove it from the config.

\n

Example:

\n
$ curl -X PATCH http://localhost:8000/__marmite__/config \\\n  -H 'Content-Type: application/json' \\\n  -d '{"pagination": 20, "enable_search": true}'\n
\n

Response (200):

\n
{\n  "file": "marmite.yaml",\n  "config": { "...merged config..." }\n}
\n

Site Data

\n

Get aggregated data

\n
GET /__marmite__/data\n
\n

Returns aggregated site data useful for building tools and editors. Includes lists of all tags, streams, series, authors, languages, content slugs, the full site config, and build stats.

\n

Response (200):

\n
{\n  "tags": ["docs", "rust", "tutorial"],\n  "streams": ["guide", "news"],\n  "series": ["python-tutorial"],\n  "authors": ["alice"],\n  "languages": ["en", "pt"],\n  "iso_languages": ["aa", "ab", "...all ISO 639-1 codes..."],\n  "slugs": ["about", "hello-world", "my-post"],\n  "post_count": 25,\n  "page_count": 3,\n  "elapsed_time": 0.6,\n  "marmite_version": "0.4.1",\n  "config": { "...full marmite.yaml config..." }\n}
\n

Dev Server Assets

\n

These endpoints serve the marmite-toolbar assets and are injected automatically into HTML pages during --serve mode.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EndpointDescription
GET /__marmite__/toolbar.jsToolbar JavaScript
GET /__marmite__/toolbar.cssToolbar stylesheet
GET /__marmite__/livereload.jsLive reload script (with --watch)
WS /__marmite__/livereloadLive reload WebSocket (with --watch)
\n

Content Metadata

\n

When running with --serve, marmite generates a metadata JSON file for each content page:

\n
GET /{slug}.metadata.json\n
\n

Response:

\n
{\n  "frontmatter": {\n    "title": "My Post",\n    "slug": "my-post",\n    "date": "2026-07-09 12:00:00",\n    "tags": ["rust", "tutorial"],\n    "...all frontmatter fields..."\n  },\n  "source_path": "posts/my-post.md",\n  "last_updated": "2026-07-09T12:00:00+00:00"\n}
\n

Content Body

\n

Read content body

\n
GET /__marmite__/content/{slug}/body\n
\n

Returns the raw markdown body and frontmatter separately. Used by the marmite-editor.

\n

Response:

\n
{\n  "slug": "my-post",\n  "frontmatter": {"title": "My Post", "tags": "rust, web", "...": "..."},\n  "body": "# My Post\\n\\nContent here...",\n  "source_path": "content/my-post.md"\n}
\n

Write content body

\n
PUT /__marmite__/content/{slug}/body\nContent-Type: application/json\n\n{"body": "# Updated\\n\\nNew content...", "frontmatter": {"title": "Updated Title"}}\n
\n

The frontmatter field is optional. When provided, the specified fields are merged into the existing frontmatter. The body is written as-is without adding or removing frontmatter delimiters (the function handles serialization).

\n

Raw File Access

\n

Read file

\n
GET /__marmite__/file/{path}\n
\n

Reads any text file in the project directory. Binary files (images, fonts, archives) are rejected. Path traversal outside the project directory is blocked.

\n

Response:

\n
{"path": "content/_hero.md", "content": ">>> Welcome to my site >>>"}
\n

Write file

\n
PUT /__marmite__/file/{path}\nContent-Type: application/json\n\n{"content": ">>> Updated hero content >>>"}\n
\n

File Tree

\n
GET /__marmite__/files\n
\n

Lists all files in the project directory (excluding the output folder and hidden files). Each entry includes flags for whether the file is editable, a content file with a slug, or a fragment.

\n

Response:

\n
{\n  "files": [\n    {"path": "content/my-post.md", "slug": "my-post", "editable": true},\n    {"path": "content/_hero.md", "editable": true, "fragment": true},\n    {"path": "marmite.yaml", "editable": true},\n    {"path": "static/custom.css", "editable": true},\n    {"path": "content/media/photo.jpg"}\n  ]\n}
\n

Raw Config Access

\n

Read config

\n
GET /__marmite__/config\n
\n

Returns the raw YAML content of marmite.yaml.

\n

Response:

\n
{"file": "/path/to/marmite.yaml", "yaml": "name: My Site\\ntagline: ..."}
\n

Write config

\n
PUT /__marmite__/config\nContent-Type: application/json\n\n{"yaml": "name: My Site\\ntagline: Updated\\n..."}\n
\n

The YAML is validated before writing. Returns 400 with an error message if the YAML is malformed.

\n

Error responses

\n

All endpoints return JSON error responses:

\n
{"error": "description of the error"}
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StatusMeaning
400Bad request (missing fields, invalid JSON)
404Content or config not found
405HTTP method not allowed
409Conflict (config already exists)
500Server error (file write failed)
\n
\n

Please consider giving a ☆ on Marmite Github repository, that helps a lot!

\n
\n\n\n", "summary": "\"Marmite exposes a local REST API during --serve mode for creating, editing, moving, cloning, and deleting content, plus managing site configuration.\"", "date_published": "2026-07-09T12:00:00-00:00", "image": "media/content-management-api.banner.jpg", "authors": [ { "name": "Bruno Rocha", "url": "https://go.rocha.social/@bruno", "avatar": "https://github.com/rochacbruno.png" } ], "tags": [ "docs", "features", "api", "server" ], "language": "en" } ] }