Core Concepts

Before diving into configuration, let's understand the fundamental concepts that make Vellocs work.

What is Vellocs?

Think of Vellocs as a documentation website builder. You write your documentation in simple text files (with Markdown), configure how your site looks and behaves through a single JSON file, and Vellocs generates a beautiful, fast website.

How It Works

Here's the simple flow:

/docs
  /guides
    introduction.mdx
    installation.mdx
  /components
    accordion.mdx

{
  "name": "My Docs",
  "colors": {
    "accent": "#6366F1"
  }
}

Key Concepts

MDX Files

MDX is Markdown with superpowers. It's just regular text with some special syntax:

# This is a heading

This is a paragraph with **bold** and *italic* text.

- Bullet point 1
- Bullet point 2

<Alert type="info">
  This is a special component!
</Alert>

When you write in MDX, you get:

• Markdown syntax - Familiar formatting like # for headings and **bold**
• Components - Special blocks like <Alert>, <Tabs>, <CodeBlock> that add interactive features
• No HTML knowledge needed - Just use the components we provide

File Structure

Your Vellocs project has a simple structure:

• docs/ - Where all your documentation lives
• docs/config.json - The main configuration file

The config.json File

This is the most important file in your project. It's a configuration file written in JSON format.

What is JSON?

JSON is just a way to store information in a structured format. It looks like this:

{
  "name": "My Value",
  "number": 42,
  "enabled": true,
  "list": ["item1", "item2"]
}

Rules for JSON:

1. Everything is in {} curly braces
2. Properties have names in "quotes"
3. Use : after the property name
4. Separate properties with , commas
5. Text values need "quotes", numbers and true/false don't

Navigation Structure

One of the most important parts of config.json is the navigation. Think of it like a table of contents for your site.

Here's how it's organized:

Tabs (top level sections)
└── Groups (categories within a tab)
    └── Pages (individual documents)

Example:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "icon": "rocket",
            "pages": [
              "guides/introduction",
              "guides/installation"
            ]
          }
        ]
      }
    ]
  }
}

This creates:

• A "Documentation" tab at the top
• A "Getting Started" section in the sidebar
• Two pages: Introduction and Installation

Important: Page paths in the pages array:

• Don't include /docs/ at the start
• Don't include .mdx at the end
• Just use the folder path and filename

So /docs/guides/introduction.mdx becomes "guides/introduction"

How Pages are Created

When you add a file to /docs and reference it in config.json, Vellocs automatically:

1. Reads the MDX file - Gets your content
2. Parses the frontmatter - The metadata at the top of your file
3. Generates a URL - Based on the file path
4. Creates the page - With navigation, table of contents, and styling
5. Adds it to the navigation - Based on your config.json configuration

Page Frontmatter

Every MDX file should start with frontmatter - metadata about the page:

---
title: My Page Title
description: A short description of this page
---

# Content starts here...

Available frontmatter fields:

• title - Page title (shown in browser tab and navigation)
• description - Short description (used for SEO and previews)
• order - Optional number to control sort order within a group

Color System

Vellocs uses a design token system for colors. Instead of hardcoding colors everywhere, we use named tokens:

• background - Main page background
• foreground - Main text color
• primary - Your brand color
• accent - Links and highlights
• muted - Subtle text and backgrounds
• border - Border colors

Why use tokens?

• Change one color in config.json and it updates everywhere
• Ensures visual consistency
• Makes dark mode work automatically

{
  "colors": {
    "accent": "#6366F1",
    "background": "#0C0A09"
  }
}

Static Site Generation

Vellocs uses static site generation (SSG). This means:

1. When you build your site, Vellocs generates HTML files for every page
2. These HTML files are complete, pre-rendered pages
3. No server needed - just upload files to any host
4. Pages load instantly because they're already built

Benefits:

• ⚡ Blazing fast - No server processing needed
• 🔒 Secure - No server to hack
• 💰 Free hosting - Can host on GitHub Pages, Vercel, Netlify for free
• 📈 Scales infinitely - Static files can handle any traffic

Development vs Production

npm run dev

Next Steps

Now that you understand the basics, you're ready to: