---
sidebar_position: 2.2
sidebar_label: "Slide Directory"
sidebar_custom_props:
  section: "Features"
  section_position: 2
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# Slide Directory

Organize your presentations into directories for better navigation and grouping. This is especially useful when you have many presentations that belong to different categories, modules, or topics.

## Directory Structure

Create subdirectories within your `path` directory to group presentations:

```
slidev/
├── introduction.md           # Root-level presentation
├── getting-started.md        # Root-level presentation
├── advanced/                  # Category directory
│   ├── _category_.yml         # Category metadata (optional)
│   ├── networking.md
│   └── security.md
└── workshops/                 # Another category
    ├── _category_.yml
    ├── hands-on-docker.md
    └── kubernetes-basics.md
```

## Category Metadata

Configure category appearance using `_category_.yml` or `_category_.json`:

<Tabs>
  <TabItem value="yaml" label="YAML" default>
    ```yaml title="slidev/advanced/_category_.yml"
    label: "Advanced Topics"
    description: "Deep dives into complex subjects"
    position: 2
    ```
  </TabItem>
  <TabItem value="json" label="JSON">
    ```json title="slidev/advanced/_category_.json"
    {
      "label": "Advanced Topics",
      "description": "Deep dives into complex subjects",
      "position": 2
    }
    ```
  </TabItem>
</Tabs>

| Field         | Type     | Default        | Description                                      |
| ------------- | -------- | -------------- | ------------------------------------------------ |
| `label`       | `string` | Directory name | Display name shown in overview                   |
| `description` | `string` | `undefined`    | Brief description shown in category card/listing |
| `position`    | `number` | `99`           | Sort order (lower numbers appear first)          |

:::tip[No metadata file?]
If you don't create a `_category_.yml` file, the directory name will be used as the label (converted to title case: `my-category` → `My Category`).
:::

## Overview Navigation

The overview page adapts to show directory content:

### Root Level View

Shows:

- All root-level presentations
- Category folders as clickable cards

### Category View

When clicking a category folder:

- Shows presentations within that category
- Displays a back button to return to parent
- Category label and description replace the default title

## URL Structure

Presentations in directories have paths that reflect their location:

| File Path                       | Presentation URL               |
| ------------------------------- | ------------------------------ |
| `slidev/intro.md`               | `/slides/intro/`               |
| `slidev/advanced/networking.md` | `/slides/advanced/networking/` |
| `slidev/workshops/docker.md`    | `/slides/workshops/docker/`    |

Category overview pages are accessible at:

| Category Path | Overview URL        |
| ------------- | ------------------- |
| Root          | `/slidev`           |
| `advanced`    | `/slidev/advanced`  |
| `workshops`   | `/slidev/workshops` |

## Grid vs List View

Both views support directory navigation:

### Grid View

- Categories appear as folder cards with an icon
- Shows category label, description, and presentation count
- Click to navigate into the category

### List View

- Categories appear as rows with folder icon prefix
- Compact display with label, description, and count
- Same click-to-navigate behavior

## Nested Directories

You can nest directories multiple levels deep:

```
slidev/
└── training/
    ├── _category_.yml
    ├── beginner/
    │   ├── _category_.yml
    │   └── basics.md
    └── advanced/
        ├── _category_.yml
        └── expert-tips.md
```

The back button always navigates to the parent level, allowing easy traversal through nested structures.

## Sorting Within Categories

Presentations within a category follow the same sorting rules:

1. `position` frontmatter (if specified)
2. `sourcePath` (natural filename sorting)
3. `title` (alphabetical fallback)

Categories themselves are sorted by their `position` field, then by label.

## Example Configuration

```yaml title="slidev/modules/_category_.yml"
label: "Course Modules"
description: "Step-by-step learning path for the complete course"
position: 1
```

```markdown title="slidev/modules/module-01-intro.md"
---
title: "Module 1: Introduction"
description: "Getting started with the fundamentals"
position: 1
---

# Introduction

Welcome to Module 1!
```

```markdown title="slidev/modules/module-02-basics.md"
---
title: "Module 2: Core Concepts"
description: "Understanding the building blocks"
position: 2
---

# Core Concepts

Let's explore the basics...
```

## Backward Compatibility

- **Flat structures still work** - If you don't use directories, everything works as before
- **Mixed structures supported** - You can have both root-level files and directories
- **No configuration required** - Directory support is automatic