How to Configure the Content Directory Structure and Front-Matter Options in Astro Big Doc

Set the CONTENT environment variable or modify config.js to define your root directory, then organize Markdown files in hierarchical folders and use title, slug, and order front-matter fields to control navigation labels, URLs, and menu positioning.

The astro-big-doc repository provides a documentation site generator built on Astro that automatically builds navigation menus from your Markdown content. Understanding how to configure the content directory structure and front-matter options allows you to control exactly how your documentation is organized and displayed without manually editing navigation configuration files.

Setting the Content Root Directory

The generator scans a specific folder for Markdown files based on configuration settings in config.js and environment variables.

Using config.js

In config.js, the content_path property defines the directory containing your documentation files. The default configuration uses ./content relative to the project root.

The relevant logic appears in config.js where the content directory is resolved:

const contentdir = process.env.CONTENT 
  ? join(rootdir, process.env.CONTENT) 
  : join(rootdir, "content");

Overriding with Environment Variables

You can override the default path without modifying source code by setting the CONTENT environment variable in your .env file or shell environment:

# .env

CONTENT=./docs

After restarting the development server with pnpm run dev, the generator reads files from the ./docs directory instead of the default ./content folder.

Organizing the Content Directory Structure

The directory hierarchy directly maps to the menu hierarchy when using url_type: "dir" configuration. Files placed at the root level or inside folders become leaf-menu items positioned according to their location in the filesystem.

A typical structure looks like this:

content/
├── readme.md                # Home page → URL `/`

├── guides/
│   ├── intro.md            # Menu path: "Guides / Intro"

│   └── advanced.md         # Menu path: "Guides / Advanced"

└── reference/
    └── api.md              # Menu path: "Reference / API"

The parser in integration-content-structure.js builds a flat list of documents from every .md file found, then create_menu.js groups these by section and applies ordering logic based on front-matter values.

Configuring Front-Matter Options for Navigation

Each Markdown file can include a YAML front-matter block at the top to control how it appears in the navigation menu and what URL it uses.

Title Field

The title field sets both the menu label and the HTML <title> element (unless overridden elsewhere). This is the primary way to control how your page appears in navigation trees.

---
title: "Getting Started Guide"
---

Slug Field

The slug field optionally overrides the URL path for individual files. When url_type is set to "file", the slug replaces the filename in the generated URL, while folder names remain in the path to maintain filesystem synchronization.

For folders, the slug front-matter is ignored—the folder name always appears in the URL to keep paths aligned with the directory structure.

---
title: "Deep Dive Tutorial"
slug: "deep-dive"
---

With the above front-matter, a file located at content/guides/tutorial.md would generate the URL /guides/deep-dive instead of /guides/tutorial.

Order Field

The order field accepts a numeric value where lower numbers appear higher in the menu. Items without an explicit order receive a default value of 100, placing them after items with lower order values.

---
title: "Configuration Reference"
order: 5
---

In create_menu.js, the sorting logic processes the order field to determine the final menu sequence, as seen in the top_items sorting implementation.

How the Menu Generation Works

Understanding the pipeline helps debug configuration issues:

1. Collection Phase: integration-content-structure.js runs collect(collect_config) to scan the content directory and write document_list.json inside the .structure folder.

2. Raw Menu Creation: If menu.yaml does not exist in the content root, create_raw_menu() in create_menu.js builds a menu structure from top-level documents (level 2), inserting the home page first if present.

3. Base URL Addition: The add_base() function prepends PUBLIC_BASE environment variable values to every link if configured.

4. Section Expansion: get_section_menu() processes the menu to expand autogenerate sections or use static items from menu.yaml.

Complete Configuration Example

Directory Structure:

docs/
├── readme.md
├── installation.md
├── guides/
│   ├── setup.md
│   └── deployment.md
└── api/
    └── endpoints.md

docs/guides/deployment.md:

---
title: "Deployment Strategies"
slug: "deploy"
order: 2
---

# Deployment Strategies

Content here...

.env:

CONTENT=./docs
PUBLIC_BASE=/documentation

Resulting Menu Structure:

The generated public/menu.json will include:

• Home (/documentation/)
• Installation (/documentation/installation)
• Guides section containing:
  • Setup (default order 100)
  • Deployment (/documentation/guides/deploy with order 2, appearing before Setup)

Summary

• Set your content root using the CONTENT environment variable or modify content_path in config.js (default: ./content).
• Organize files in folders to create menu hierarchies; the directory structure maps directly to navigation sections.
• Use front-matter fields to control presentation: title for labels, slug for custom URLs (files only), and order for sort position (lower values appear first, default is 100).
• The system automatically generates public/menu.json through the pipeline defined in integration-content-structure.js and create_menu.js.

Frequently Asked Questions

What is the default content directory in astro-big-doc?

The default content directory is ./content relative to the project root, as defined in config.js. You can override this by setting the CONTENT environment variable to point to a different folder, such as ./docs or ./documentation.

How does the slug front-matter option affect URLs?

For individual files with url_type: "file", the slug value replaces the filename in the generated URL path. For example, a file named tutorial.md with slug: "guide" generates the URL /folder/guide instead of /folder/tutorial. However, for folders, the slug front-matter is ignored to maintain synchronization between the filesystem and URLs.

What happens if I don't specify an order value in the front-matter?

If you omit the order field, the system assigns a default value of 100 during menu generation in create_menu.js. This places items without explicit ordering after items with lower numeric values. To prioritize specific pages, assign them order values lower than 100.

Can I use a custom base URL for all generated links?

Yes, set the PUBLIC_BASE environment variable in your .env file. The add_base() function in the integration prepends this value to every generated link in the menu. For example, setting PUBLIC_BASE=/docs changes home links from / to /docs/ and section links from /guides/ to /docs/guides/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}