DOCSEARCHbyAlgolia
Submit Docs

Outstatic CMS

repository·canary·Indexed 11 days ago

https://github.com/avitorio/outstatic

A Git-based CMS that provides a visual dashboard for managing Markdown and MDX content. Outstatic eliminates the need for a database by committing content directly to GitHub, making it ideal for static sites and Next.js projects.

Tokens
47K
Snippets
134
Records
244
Agent score
84%

What's inside Outstatic

  1. What is Outstatic?

    canary

    Outstatic is a static CMS designed for Markdown and MDX content. It provides a visual dashboard for creating, editing, and publishing content, which is then automatically committed directly to your GitHub repository.

    Key characteristics include:

    • No Database: Content is stored as files in your GitHub repository rather than in a traditional database.
    • No Hosted Backend: You can use the hosted dashboard or self-host it within your own Next.js application.
    • GitHub-Centric: Uses GitHub for both content storage and authentication.
    • Structured Content: Supports adding custom fields for structured data and AI completions for writing assistance.

  2. Explore the documentation project structure

    canary

    The documentation application is organized into the following key routes and files:

    • app/(home): Route group for the landing page and other general pages.
    • app/docs: The main documentation layout and pages.
    • app/api/search/route.ts: The Route Handler responsible for search functionality.
    • lib/layout.shared.tsx: Contains shared layout options (recommended to keep for consistency).
    • lib/source.ts: Implementation of the content source adapter using loader().

  3. Tech stack used in Outstatic Advanced Blog

    canary

    The Advanced Blog example utilizes the following technologies:

    • Outstatic: The core CMS framework.
    • Next.js: The React framework for the application.
    • TailwindCSS: For styling.
    • MDX: For writing content using Markdown with React components.
    • Vercel OG: For dynamic Open Graph image generation.

    For a complete list of dependencies, consult the package.json file in the project root.

  4. What is an Outstatic Project?

    canary

    An Outstatic Project is a management boundary hosted on outstatic.com. It acts as the bridge between the hosted Outstatic dashboard and your GitHub repository.

    Key functions of a project include:

    • Content Management: Managing content stored in a connected GitHub repository, branch, or monorepo folder via the hosted dashboard.
    • User Management: Managing users and assigning roles for content access.
    • Pro Integration: For Pro subscribers, a project provides a single API key to enable advanced features on a self-hosted instance, such as AI Completions, Member Management, Google/Email Login, and Automatic Content Setup.

    Note: A project is an access and integration boundary, not a content type. Content remains in your GitHub repository as Markdown and is not moved to an Outstatic database.

  5. What is the Block Library?

    canary

    The Block Library allows you to define reusable MDX components that editors can insert directly into documents using the slash command menu (/).

    Each block definition includes:

    • The Component Name (the exported MDX component).
    • Props that editors fill in via a UI form.
    • Imports that are automatically added to the top of the document.
    • Additional attributes that are appended verbatim to every insertion.

    Blocks are stored as a JSON file in your repository's content folder, meaning they are versioned alongside your content via GitHub.

  6. How Outstatic works

    canary

    Outstatic is a markdown-based Content Management System (CMS) that operates without a dedicated database or server. Instead, all content is stored directly in your GitHub repository as markdown files.

    When using the Outstatic dashboard to create or edit content, the changes are committed to your repository. If you are developing your site locally, you must pull these changes from GitHub to your local environment to see them reflected in your development server.

  7. Understand how custom fields are stored and fetched

    canary

    Storage Mechanism

    Custom fields are defined in a schema file located at /outstatic/content/{collection}/schema.json. This file defines the properties, types, and requirements for the collection.

    Fetching Data

    • ID Generation: Outstatic converts your field name into a camelCase ID. Use this ID to access the data in your frontend queries.
    • Query Scope: Custom fields are unique to a specific collection. While metadata queries can operate across all collections, you should narrow your query by the specific collection if you need to target specific custom fields.
    {
  "title": "projects",
  "type": "object",
  "properties": {
    "websiteUrl": {
      "required": false,
      "description": "website url",
      "fieldType": "String",
      "dataType": "string",
      "title": "website url"
    },
    "websiteSummary": {
      "required": false,
      "description": "Summary",
      "fieldType": "Text",
      "dataType": "string",
      "title": "website summary"
    }
  }
}

  8. Understand Outstatic core concepts: Collections and Documents

    canary

    Outstatic organizes content using a hierarchical structure of Collections and Documents:

    • Collections: Used to group related documents together (e.g., a 'Posts' collection).
    • Documents: The individual content entries within a collection that contain the actual data.

    You can customize these collections by adding Custom fields to tailor the data structure to your specific needs. Data is retrieved on the frontend using Outstatic's fetching functions and a metadata DB.

  9. Compare Hosted vs. Self-Hosted Outstatic setups

    canary

    Outstatic can be used in two primary ways depending on your hosting and subscription model:

    1. Hosted Outstatic (outstatic.com)

    Use the hosted dashboard directly to manage content and users. This is the primary way to interact with a Project.

    2. Self-Hosted Outstatic

    You can run your own Outstatic instance. How you connect it depends on your plan:

    • Free Self-Hosting: Connect your instance directly to GitHub using your own OAuth app. This requires setting the following environment variables:

      • OST_GITHUB_ID
      • OST_GITHUB_SECRET This setup does not require an Outstatic API key.

    • Pro Self-Hosting: Connect your self-hosted instance to a Project on outstatic.com using a Project API key. This enables managed services like AI Completions, Member Management, Google/Email Login, and Automatic Content Setup.

  11. Understand Outstatic content structures: Collections, Documents, and Singletons

    canary

    Outstatic organizes content into three distinct structural components:

    1. Collections

    Collections act as categories or schemas that define the types of content available on your site (e.g., a Posts collection for a blog). They define the structure and are stored as folders in your repository at: /outstatic/content/{collection}

    2. Documents

    Documents are the individual content entries within a Collection. For example, a blog post titled "How to raise a dragon" in a posts collection would be stored at: /outstatic/content/posts/how-to-raise-a-dragon.mdx

    Each Document includes default metadata:

    • Title: The document title.
    • Content: Text and images edited via the interface.
    • Date: The publication date (available as publishedAt on the frontend).
    • Status: Either published or draft.
    • Author: GitHub name and avatar (editable).
    • URL Slug: Automatically generated from the title but manually editable.
    • Custom Fields: Additional data defined via schemas.

    3. Singletons

    Singletons are unique, one-off content items used for pages that do not repeat, such as a Homepage, About page, or Site Settings. Unlike Collections, which hold multiple documents, a Singleton exists as a single instance.

    Singletons are stored in the _singletons directory: /outstatic/content/_singletons/{singleton}.md

    Custom field schemas for Singletons are stored as {slug}.schema.json within the same _singletons directory.

  12. Configure Media Library paths in Outstatic v2.0

    canary

    Outstatic v2.0 introduces a Media Library page for managing and reusing images. While no code changes are required for existing media, you must define two specific paths to enable the new functionality:

    1. Repo Media Path: The path within your repository where media files are stored.
    2. Public Media Path: The public URL path used to access these files.

    You will be prompted to configure these paths via the Media Library page or automatically when attempting to upload an image to a document.