usemarble · mintlify · Dec 10, 2025 · Dec 10, 2025 · Dec 10, 2025 · Dec 10, 2025
diff --git a/api/endpoint/authors.mdx b/api/endpoint/authors.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Get All Authors"
-description: "Retrieves a list of all authors in a workspace."
+title: Get all authors from Marble API
+description: Retrieve all content authors from your Marble CMS workspace with pagination. Each author includes name, bio, role, social links, and post count.
 ---
 
 <RequestExample>

diff --git a/api/endpoint/categories.mdx b/api/endpoint/categories.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Get All Categories"
-description: "Retrieves a list of all categories in a workspace."
+title: Get all categories from Marble API
+description: Retrieve all content categories from your Marble CMS workspace with pagination. Each category includes name, slug, description, and post count for taxonomy management.
 ---
 
 <RequestExample>

diff --git a/api/endpoint/post.mdx b/api/endpoint/post.mdx
@@ -1,8 +1,12 @@
 ---
-title: "Get a Single Post"
-description: "Retrieves a single post by its identifier (slug or id)."
+title: Get a single post by slug or ID
+description: Retrieve a single blog post from Marble CMS using its slug or ID. Get post content in HTML or Markdown format with full metadata including authors, tags, and categories.
 ---
 
+## Overview
+
+Use this endpoint to retrieve a single blog post from your Marble CMS workspace by its slug or ID. You can request content in HTML or Markdown format.
+
 <RequestExample>
 ```bash cURL (by slug)
 curl "https://api.marblecms.com/v1/cm6ytuq9x0000i803v0isidst/posts/introducing-marblecms"

diff --git a/api/endpoint/posts.mdx b/api/endpoint/posts.mdx
@@ -1,8 +1,12 @@
 ---
-title: "Get All Posts"
-description: "Retrieves a paginated list of posts in a workspace."
+title: Get all posts from Marble API
+description: Retrieve a paginated list of blog posts from your Marble CMS workspace. Filter by category, tags, or search query. Sort by publish date with customizable pagination.
 ---
 
+## Overview
+
+Use this endpoint to retrieve all published blog posts from your Marble CMS workspace. The response includes post metadata, content, authors, categories, and tags with pagination support.
+
 <RequestExample>
 ```bash cURL
 curl "https://api.marblecms.com/v1/cm6ytuq9x0000i803v0isidst/posts"
@@ -120,6 +124,5 @@ Use query parameters to paginate, sort, and filter the results.
 <Note>
   Responses include a `pagination` object with `limit`, `currentPage`,
   `previousPage`, `nextPage`, `totalPages`, and `totalItems`. For advanced usage
-  and error cases (like invalid page numbers), see the full guide on
-  <a href="/api/pagination">Pagination</a>.
+  and error cases (like invalid page numbers), see the [Pagination guide](/api/pagination).
 </Note>
diff --git a/api/endpoint/tags.mdx b/api/endpoint/tags.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Get All Tags"
-description: "Retrieves a list of all tags in a workspace."
+title: Get all tags from Marble API
+description: Retrieve all content tags from your Marble CMS workspace with pagination. Each tag includes name, slug, description, and post count for content organization.
 ---
 
 <RequestExample>

diff --git a/api/getting-started.mdx b/api/getting-started.mdx
@@ -1,11 +1,11 @@
 ---
-title: "Getting Started"
-description: "Get started with the Marble API."
+title: Getting started with Marble API
+description: Learn how to authenticate and make your first API request to Marble CMS. Try the API with our example workspace or use your own workspace key.
 ---
 
-## Trying it out
+## Try the API without an account
 
-Throughout this documentation, we use an example workspace ID: `cm6ytuq9x0000i803v0isidst`. You can use this ID to make live API requests and see real responses without needing an account.
+Throughout this documentation, we use an example workspace ID: `cm6ytuq9x0000i803v0isidst`. You can use this workspace ID to make live API requests and see real responses without creating a Marble CMS account.
 
 <Tip>
   Try it now! Copy and paste this command into your terminal to fetch posts from our example workspace:

diff --git a/api/introduction.mdx b/api/introduction.mdx
@@ -1,9 +1,13 @@
 ---
-title: "Introduction"
-description: "Welcome to the Marble API."
+title: Marble API introduction
+description: The Marble API is a REST API for managing headless CMS content. Access posts, categories, tags, and authors via HTTPS with JSON responses from api.marblecms.com.
 ---
 
-The Marble API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and verbs.
+## What is the Marble API?
+
+The Marble API is a RESTful API for managing headless CMS content. It provides programmatic access to your blog posts, authors, categories, and tags through simple HTTP requests.
+
+The API is organized around REST principles with predictable resource-oriented URLs, JSON-encoded responses, and standard HTTP response codes and verbs.
 
 ## Base URL
 

diff --git a/api/pagination.mdx b/api/pagination.mdx
@@ -1,13 +1,15 @@
 ---
-title: "Pagination"
-description: "Learn how to use pagination in the Marble API."
+title: Marble API pagination guide
+description: Learn how to use offset-based pagination in Marble CMS API. Control page size, navigate pages, and handle pagination metadata for posts, categories, tags, and authors.
 ---
 
-Marble API uses offset-based pagination for endpoints that return multiple items. Pagination metadata is included in every response to help you navigate through large datasets efficiently.
+## What is pagination?
 
-## How Pagination Works
+Marble API uses offset-based pagination for endpoints that return multiple items. Pagination allows you to retrieve large datasets in smaller, manageable chunks rather than loading everything at once.
 
-When you request a list of resources (like posts), the API automatically includes pagination information in the response. This allows you to:
+## How pagination works in Marble API
+
+When you request a list of resources (like posts, categories, or tags), the API automatically includes pagination metadata in every response. This allows you to:
 
 - Control how many items are returned per request
 - Navigate to specific pages

diff --git a/api/rate-limits.mdx b/api/rate-limits.mdx
@@ -1,13 +1,13 @@
 ---
-title: "Rate Limits"
-description: "Understand how Marble API rate limiting works and what quotas apply to your requests."
+title: Marble API rate limits and quotas
+description: Understand Marble CMS API rate limiting with 200 requests per 10 seconds per workspace. Learn about rate limit headers, 429 errors, and best practices for handling limits.
 ---
 
 Marble applies global rate limits to protect the stability of the API for all users. This page explains the limits, how they are calculated, and how to design your integration to handle them gracefully.
 
-## Overview
+## What are rate limits?
 
-Marble API uses rate limiting to ensure fair usage and API stability. Rate limits are enforced per workspace using a sliding window approach.
+Rate limits control how many API requests you can make within a specific time window. Marble API uses rate limiting to ensure fair usage and API stability for all users. Rate limits are enforced per workspace using a sliding window approach.
 
 <Info>
 Most applications will not hit these limits during normal use, but you should still build in defensive handling for rate limit responses.

diff --git a/api/types.mdx b/api/types.mdx
@@ -1,6 +1,6 @@
 ---
-title: "TypeScript Types"
-description: "TypeScript type definitions for Marble API responses."
+title: TypeScript types for Marble API
+description: Complete TypeScript type definitions and Zod schemas for Marble CMS API responses. Includes types for posts, authors, categories, tags, and pagination with npm package.
 ---
 
 This page provides TypeScript type definitions for all Marble API responses. These types can be used to ensure type safety when integrating Marble with TypeScript projects.
@@ -126,7 +126,7 @@ export type MarbleAuthorListResponse = {
 ```
 
 <Tip>
-Copy these type definitions into a `types/marble.ts` file in your project. If you prefer a published package, we also provide an official npm package that exports these types .
+Copy these type definitions into a `types/marble.ts` file in your project. If you prefer a published package, we also provide an official npm package `@usemarble/core` that exports these types.
 </Tip>
 
 ### NPM package

diff --git a/guides/features/extra/reading-time.mdx b/guides/features/extra/reading-time.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Reading Time"
-description: "How to display reading time for posts."
+title: Calculate reading time for blog posts
+description: Display estimated reading time for Marble CMS blog posts. Simple JavaScript function based on 238 words per minute average reading speed.
 ---
 
 Some blogs like to show an estimated reading time for each post. Marble provides these estimates inside the editor interface, but you can also display them on the frontend of your site.

diff --git a/guides/features/import.mdx b/guides/features/import.mdx
@@ -1,6 +1,6 @@
 ---
-title: Importing
-description: See which Markdown and MDX syntax Marble supports when you import existing content.
+title: Import Markdown and MDX to Marble CMS
+description: Import existing Markdown and MDX files to Marble CMS. Supports headings, lists, links, images, code blocks, and preserves MDX components for your application.
 ---
 
 You can bring your existing `.md` and `.mdx` files into Marble. During import, Marble preserves the most commonly used Markdown and MDX syntax so you do not have to rewrite your content.

diff --git a/guides/features/webhooks.mdx b/guides/features/webhooks.mdx
@@ -1,10 +1,14 @@
 ---
-title: Webhooks
-description: Using webhooks to trigger builds and automate workflows.
+title: Marble CMS webhooks for automation
+description: Use Marble CMS webhooks to trigger builds, revalidate content, and automate workflows. Powered by Upstash QStash with signature verification for security.
 tag: "NEW"
 ---
 
-Webhooks provide a powerful way to keep your site's content fresh and automate workflows. When an event occurs in your Marble workspace (like publishing a post), we can send an HTTP POST payload to a URL you configure. Webhooks are powered by [Upstash QStash](https://upstash.com?utm_source=marble-docs), ensuring reliable delivery of events.
+## What are webhooks?
+
+Webhooks provide a powerful way to keep your site's content fresh and automate workflows. When an event occurs in your Marble CMS workspace (like publishing a post), Marble sends an HTTP POST request with event data to a URL you configure. 
+
+Marble webhooks are powered by [Upstash QStash](https://upstash.com?utm_source=marble-docs), ensuring reliable delivery of events with automatic retries.
 
 ## Use cases
 
@@ -149,7 +153,7 @@ export async function POST(request: Request) {
 }
 ```
 
-<Note>If you want a better guide on how to invalidate cache in your framework of choice, you can check out our blog post on [Using Marble's Webhooks with the Next.js App Router](https://marblecms.com/blog/nextjs-webhooks-with-marble).</Note>
+<Note>For a detailed guide on cache invalidation in Next.js, see our blog post on [Using Marble's Webhooks with the Next.js App Router](https://marblecms.com/blog/nextjs-webhooks-with-marble). For other frameworks, check our [integration guides](/guides/integrations/nextjs).</Note>
 
 Marble will send the signature in the `x-marble-signature` header of the request. You can use this signature to verify the authenticity of the request. Make sure to add the `process.env.MARBLE_WEBHOOK_SECRET` environment variable.
 

diff --git a/guides/integrations/astro.mdx b/guides/integrations/astro.mdx
@@ -1,8 +1,12 @@
 ---
-title: "Astro"
-description: "Integrate Marble in your Astro application"
+title: Integrate Marble CMS with Astro
+description: Use Marble CMS with Astro Content Collections. Fetch blog posts with type-safe loaders, generate static pages, and render content with full TypeScript support.
 ---
 
+## Overview
+
+This guide shows you how to integrate Marble CMS with Astro using Content Collections. You'll learn how to fetch blog posts with type-safe loaders, generate static pages, and render content with full TypeScript support.
+
 To integrate Marble in your Astro application, you first need an Astro site. If you don't have one, you can check out the [Astro documentation](https://docs.astro.build/en/tutorial/0-introduction/) to get started, or use our [Astro blog template](https://github.com/usemarble/astro-example) for a ready-to-go solution.
 
 Astro's **Content Collections** are the best way to manage content in your project. We'll use a **Content Loader** to fetch your posts from Marble and make them available in your Astro site with full type-safety. You can learn more about this in the [Astro Content Collections documentation](https://docs.astro.build/en/guides-collections/).
@@ -33,8 +37,7 @@ Next, define your content collection. This tells Astro how to fetch and validate
 This configuration defines a `posts` collection, and includes a loader function that fetches your posts from the Marble API.
 
 <Note>
-  For complete TypeScript type definitions, see our [Types
-  reference](/api/types). The schema below matches the `Post` type from the API.
+  For complete TypeScript type definitions, see our [TypeScript types reference](/api/types). The schema below matches the `Post` type from the Marble API.
 </Note>
 
 ```typescript src.config.ts

diff --git a/guides/integrations/nextjs.mdx b/guides/integrations/nextjs.mdx
@@ -1,9 +1,13 @@
 ---
-title: "Next.js"
-description: "Integrate Marble in your Next.js application"
+title: Integrate Marble CMS with Next.js
+description: Build a blog with Marble CMS and Next.js. Fetch content via REST API, display posts with server-side rendering, and style with Tailwind Typography. Includes TypeScript examples.
 ---
 
-Getting your content to your Next.js site is as simple as making an API request to the Marble API. This guide will walk you through setting up a blog with Marble and Next.js.
+## Overview
+
+This guide shows you how to integrate Marble CMS with Next.js to build a blog. You'll learn how to fetch content from the Marble API, display posts with server-side rendering, and style content with Tailwind Typography.
+
+Getting your content to your Next.js site is as simple as making an API request to the Marble API.
 
 If you want to get started quickly, you can clone our [Next.js blog template](https://github.com/usemarble/nextjs-example).
 
@@ -34,9 +38,7 @@ To make it easier to fetch data from Marble, you can create a utility file to wr
 Create a file at `lib/query.ts` (or `.js` if you're using JavaScript).
 
 <Note>
-  For complete TypeScript type definitions, see our [TypeScript Types
-  reference](/api/types). The server functions below use these types for full
-  type safety.
+  For complete TypeScript type definitions, see our [TypeScript types reference](/api/types). The server functions below use these types for full type safety.
 </Note>
 
 ```typescript lib/query.ts

diff --git a/guides/integrations/tanstack.mdx b/guides/integrations/tanstack.mdx
@@ -1,9 +1,13 @@
 ---
-title: "TanStack Start"
-description: "Integrate Marble in your TanStack Start application"
+title: Integrate Marble CMS with TanStack Start
+description: Build a blog with Marble CMS and TanStack Start. Use server functions to fetch content, create dynamic routes, and style with Tailwind Typography. Full TypeScript support.
 ---
 
-Getting your content to your TanStack Start site is as simple as making an API request to the Marble API. This guide will walk you through setting up a blog with Marble and TanStack Start.
+## Overview
+
+This guide shows you how to integrate Marble CMS with TanStack Start to build a blog. You'll learn how to use server functions to fetch content, create dynamic routes, and style with Tailwind Typography.
+
+Getting your content to your TanStack Start site is as simple as making an API request to the Marble API.
 
 If you want to get started quickly, you can clone our [TanStack Start blog template](https://github.com/usemarble/tanstack-start-example).
 
@@ -44,9 +48,7 @@ npm install zod
 ```
 
 <Note>
-  For complete TypeScript type definitions, see our [TypeScript Types
-  reference](/api/types). The server functions below use these types for
-  full type safety.
+  For complete TypeScript type definitions, see our [TypeScript types reference](/api/types). The server functions below use these types for full type safety.
 </Note>
 
 ```typescript lib/query.ts

diff --git a/guides/introduction.mdx b/guides/introduction.mdx
@@ -1,9 +1,13 @@
 ---
-title: Introduction
-description: "Welcome to Marble"
+title: Introduction to Marble CMS
+description: Marble is a simple, headless CMS built for writers and developers. Manage and publish content with a clean editor, flexible REST API, and team collaboration features.
 ---
 
-**Marble is a simple, headless CMS built for writers and developers.** It helps you manage and publish content without the complexity of traditional CMS platforms.
+Marble is a simple, headless CMS built for writers and developers. It helps you manage and publish content without the complexity of traditional CMS platforms.
+
+## What is Marble CMS?
+
+Marble CMS is a headless content management system that provides a clean writing interface and a flexible REST API. Unlike traditional CMS platforms, Marble separates content management from presentation, allowing you to use any frontend framework like Next.js, Astro, or TanStack Start.
 
 ## Why use Marble?
 

diff --git a/guides/quickstart.mdx b/guides/quickstart.mdx
@@ -1,11 +1,11 @@
 ---
-title: "Quickstart"
-description: "This guide will walk you through setting up your Marble account and creating your first workspace."
+title: Quickstart guide for Marble CMS
+description: Set up your Marble CMS account, create your first workspace, and publish your first post in minutes. Step-by-step tutorial for getting started with Marble headless CMS.
 ---
 
 <Steps>
 <Step title="Create an account">
-To get started, head over to [marblecms.com](https://marblecms.com) and click the **Sign Up** button. You can sign up with your email, Google, or a GitHub account.
+To get started with Marble CMS, head over to [marblecms.com](https://marblecms.com) and click the **Sign Up** button. You can sign up with your email, Google, or a GitHub account.
 
 <Frame>
   <picture>
@@ -90,12 +90,14 @@ When you're ready, you can save your post as a draft or publish it immediately.
 <Step title="Next Steps">
 That's it! You've successfully set up your Marble workspace and created your first post. 🚀
 
-Now you're ready to connect your content to your frontend. Check out our integration guides to get started. For faster integration, add the [Context7 MCP server](https://context7.com/websites/marblecms) to your setup.
+Now you're ready to connect your content to your frontend. Check out our [integration guides](/guides/integrations/nextjs) to get started. For faster integration, add the [Context7 MCP server](https://context7.com/websites/marblecms) to your setup.
 
 <CardGroup>
   <Card title="Next.js Integration" href="/guides/integrations/nextjs" icon="react" />
   <Card title="Astro Integration" href="/guides/integrations/astro" icon="stars" />
   <Card title="TanStack Start Integration" href="/guides/integrations/tanstack" icon="tree-palm" />
 </CardGroup>
+
+You can also explore the [Marble API documentation](/api/introduction) to learn more about available endpoints.
 </Step>
 </Steps>