Adding Document

Adding New Documentation Pages

This guide will walk you through the process of adding new documentation pages to your Dockit site, organizing them properly, and ensuring they appear in the navigation.

File Structure

All documentation files are located in the src/content/docs/ directory. The structure looks like this:

Creating a New Page

Step 1: Create the File

Create a new .md or .mdx file in the appropriate directory:

For Markdown (.md):

For MDX (.mdx) - with React components:

Step 2: Add Frontmatter

Every documentation page must start with YAML frontmatter:

Required Frontmatter Fields

Field

Type

Description

title

string

Page title (appears in browser tab and navigation)

description

string

Page description for SEO and previews

Optional Frontmatter Fields

Field

Type

Description

sidebar.order

number

Custom ordering in sidebar

sidebar.label

string

Custom label in sidebar (defaults to title)

sidebar.hidden

boolean

Hide page from sidebar navigation

editUrl

boolean/string

Enable/disable edit link or set custom URL

lastUpdated

boolean

Show last updated date

prev

boolean/object

Configure previous page link

next

boolean/object

Configure next page link

hero

object

Add hero section (for splash pages)

banner

object

Add banner message

draft

boolean

Mark as draft (won’t build in production)

Adding to Navigation

Method 1: Automatic Generation

For directories with multiple pages, use autogenerate in src/config/config.json:

Method 2: Manual Configuration

For specific pages or custom organization:

Method 3: Mixed Approach

Combine autogenerate with manual items:

Content Examples

Basic Markdown Page

Next Steps

• Advanced Components

• Custom Styling

Creating New Sections

Step 1: Create Directory Structure

Step 2: Add Pages

Step 3: Update Navigation

Add to src/config/config.json:

Best Practices

File Naming

• Use kebab-case for file names: my-guide.md

• Be descriptive but concise

• Match the URL structure you want

Content Organization

1. Logical Grouping: Group related content in directories

2. Progressive Disclosure: Start with basics, advance to complex topics

3. Cross-References: Link related pages together

4. Consistent Structure: Use similar headings and organization

Writing Guidelines

1. Clear Titles: Make titles descriptive and searchable

2. Good Descriptions: Write compelling descriptions for SEO

3. Proper Headers: Use h1 for page title, h2 for main sections

4. Code Examples: Provide working, copy-paste-ready examples

5. Visual Elements: Use components, tables, and callouts for clarity

SEO and Accessibility

• Write descriptive title and description frontmatter

• Use proper heading hierarchy (h1 → h2 → h3)

• Add alt text to images

• Use semantic HTML elements

• Test with screen readers

Troubleshooting

Page Not Appearing in Navigation

1. Check file is in correct directory

2. Verify frontmatter syntax

3. Ensure page is added to config.json sidebar

4. Restart development server

Build Errors

1. Validate YAML frontmatter syntax

2. Check for missing imports in MDX files

3. Ensure all referenced files exist

4. Review component syntax

Navigation Order Issues

1. Use sidebar.order in frontmatter for custom ordering

2. Check alphabetical sorting in autogenerated sections

3. Verify manual ordering in config.json

Advanced Features

Custom Page Layouts

Use the template frontmatter field:

Page-Specific Styling

Add custom CSS classes:

Conditional Content

Use MDX to show content conditionally:

Next Steps

• Customizing Components

• Advanced Configuration

• Deployment Guide