Core Concepts

DocuBase is built on a few core concepts that make it powerful and flexible. Understanding these will help you get the most out of your documentation site.

Content Collections

Content collections are the heart of DocuBase. They provide type-safe content management with automatic schema validation.

What are Content Collections?

Content collections are groups of related content files (like documentation pages, blog posts, or tutorials) that share the same structure and schema.

src/content/
├── docs/           # Documentation collection
├── blog/           # Blog posts collection
└── tutorials/      # Tutorials collection

Why Use Collections?

// Schema ensures title is always present
schema: z.object({
  title: z.string(),
  description: z.string().optional(),
})

const posts = await getCollection('blog',
  ({ data }) => data.author === 'DocuBase Team'
);

MDX Components

MDX lets you use React/Astro components directly in your markdown content. This is what makes DocuBase documentation interactive and visually rich.

Available Components

DocuBase includes a library of pre-built components:

Using Components

Import and use components in any MDX file:

import Callout from '@/components/Callout.astro';

<Callout type="tip" title="Pro tip">
  Components make your docs more engaging!
</Callout>

Layouts and Templates

DocuBase uses layouts to provide consistent structure across pages.

Layout Hierarchy

BaseLayout
├── DocsLayout (for documentation pages)
├── BlogLayout (for blog posts)
└── Page-specific layouts

The Base Layout

Every page uses BaseLayout which provides:

• HTML document structure
• Meta tags and SEO
• Global styles
• Header and footer slots

The Docs Layout

Documentation pages use DocsLayout which adds:

• Sidebar navigation
• Table of contents
• Breadcrumbs
• Previous/Next navigation

Routing

DocuBase uses file-based routing powered by Astro.

How Routes Work

The file path determines the URL:

Dynamic Routes

DocuBase uses dynamic routes to render content collections:

src/pages/
├── docs/[...slug].astro    # Renders all docs
├── blog/[...slug].astro    # Renders all blog posts
└── tutorials/[...slug].astro

---
export async function getStaticPaths() {
  const docs = await getCollection('docs');
  return docs.map(doc => ({
    params: { slug: doc.id },
    props: { doc },
  }));
}
---

Frontmatter

Every content file starts with frontmatter—YAML metadata between --- markers.

Required vs Optional Fields

---
title: Page Title        # Required
description: Brief desc  # Optional
order: 1                 # Optional - sort order
category: Getting Started # Optional - for grouping
---

---
title: Post Title        # Required
description: Summary     # Required
pubDate: 2024-01-15     # Required
author: Author Name      # Required
tags: [tag1, tag2]      # Optional
draft: false            # Optional
---

---
title: Tutorial Title    # Required
description: What you learn # Required
difficulty: beginner     # Required
duration: 30 minutes     # Required
prerequisites: [...]     # Optional
tags: [topic1, topic2]  # Optional
---

Static Site Generation

DocuBase builds to static HTML for maximum performance and easy deployment.

Build Process

1. Content Collection - All MDX files are parsed and validated
2. Page Generation - Each route generates HTML files
3. Asset Optimization - CSS, JS, and images are optimized
4. Output - Everything goes to the dist/ folder

Benefits of Static Generation

• Fast - Pre-built HTML loads instantly
• Secure - No server-side code to exploit
• Scalable - Serve from any CDN
• Reliable - No database or runtime dependencies

Next Steps

Now that you understand the core concepts:

• Install DocuBase on your machine
• Learn how to use Components
• Check out the Tutorials for hands-on practice