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

> Configure Astro Big Doc content directory structure and front-matter options like title, slug, and order for custom navigation and URLs. Define your root via config.js or CONTENT env var.

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Set the `CONTENT` environment variable or modify [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) and environment variables.

### Using config.js

In [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) where the content directory is resolved:

```javascript
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:

```bash

# .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`](https://github.com/microwebstacks/astro-big-doc/blob/main/integration-content-structure.js) builds a flat list of documents from every `.md` file found, then [`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.

```markdown
---
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.

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

```

With the above front-matter, a file located at [`content/guides/tutorial.md`](https://github.com/microwebstacks/astro-big-doc/blob/main/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.

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

```

In [`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/integration-content-structure.js) runs `collect(collect_config)` to scan the content directory and write [`document_list.json`](https://github.com/microwebstacks/astro-big-doc/blob/main/document_list.json) inside the `.structure` folder.

2. **Raw Menu Creation**: If [`menu.yaml`](https://github.com/microwebstacks/astro-big-doc/blob/main/menu.yaml) does not exist in the content root, `create_raw_menu()` in [`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/menu.yaml).

## Complete Configuration Example

**Directory Structure:**

```

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

```

**[`docs/guides/deployment.md`](https://github.com/microwebstacks/astro-big-doc/blob/main/docs/guides/deployment.md):**

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

# Deployment Strategies

Content here...

```

**`.env`:**

```dotenv
CONTENT=./docs
PUBLIC_BASE=/documentation

```

**Resulting Menu Structure:**

The generated [`public/menu.json`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/public/menu.json) through the pipeline defined in [`integration-content-structure.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/integration-content-structure.js) and [`create_menu.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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`](https://github.com/microwebstacks/astro-big-doc/blob/main/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/`.