Content Management

Content management in Airclou is designed to be intuitive and powerful, allowing you to create, organize, and maintain your documentation, blog posts, and other content efficiently.

Overview

Airclou uses a file-based content management system built on top of Astro’s content collections. This approach gives you:

• Version Control: All content is tracked in Git
• Type Safety: Content schemas ensure data consistency
• Markdown/MDX: Write content in familiar formats with component support
• Performance: Static content generation for fast load times

Content Structure

Content is organized in the src/content directory:

src/content/
├── docs/           # Documentation pages
│   └── en/
│       ├── getting-started/
│       ├── guides/
│       └── core-concepts/
├── blog/           # Blog posts
│   └── en/
└── settings/       # Site configuration

Creating New Content

Documentation Pages

To create a new documentation page, add an MDX file in the appropriate folder:

# Create a new guide
touch src/content/docs/en/guides/my-guide.mdx

Each documentation file should include frontmatter:

---
title: My Guide
description: A brief description of this guide
order: 1
section: Guides
draft: false

# Your content here

Blog Posts

Blog posts follow a similar structure:

# Create a new blog post
touch src/content/blog/en/my-post.mdx

Blog post frontmatter:

---
title: My Blog Post
description: Post description for SEO
author: Your Name
date: 2025-01-15
tags: [tutorial, getting-started]
draft: false

# Your blog content

Frontmatter Fields

Documentation

Field	Type	Required	Description
title	string	Yes	Page title
description	string	Yes	SEO description
order	number	No	Order in navigation
section	string	No	Section grouping
draft	boolean	No	Hide from production

Blog Posts

Field	Type	Required	Description
title	string	Yes	Post title
description	string	Yes	SEO description
author	string	Yes	Author name
date	string	Yes	Publication date (YYYY-MM-DD)
tags	array	No	Post tags
draft	boolean	No	Hide from production

Using MDX Components

MDX allows you to use React components in your content:

import { Callout } from '@/components/interactive/Callout';

<Callout type="note">
  This is an informative callout with custom styling.
</Callout>

Available Components

• Callout: Highlight important information
• CodeBlock: Syntax-highlighted code examples
• QuickLinks: Grid of quick navigation links

Content Organization

Folder Structure

Organize content by:

• Topic: Group related content together
• Hierarchy: Use folders for nested navigation
• Language: Separate content by locale (en/, zh/)

Naming Conventions

• Use lowercase for file names
• Use hyphens for spaces: my-guide.mdx
• Be descriptive: authentication-setup.mdx not auth.mdx

Draft Content

Mark content as draft to hide it from production:

---
title: Work in Progress
draft: true
---

Draft content:

• Visible in development
• Hidden in production builds
• Not indexed by search engines

Publishing Workflow

1. Create: Write content in MDX files
2. Review: Preview in development mode
3. Commit: Track changes in Git
4. Deploy: Build and deploy to production

# Preview changes
pnpm dev

# Build for production
pnpm build

# Deploy
pnpm deploy

Best Practices

Writing Tips

• Clear Headings: Use descriptive section headings
• Short Paragraphs: Keep paragraphs concise
• Code Examples: Include working code samples
• Links: Cross-reference related content

SEO Optimization

• Write unique meta descriptions
• Use descriptive titles (50-60 characters)
• Include relevant keywords naturally
• Add alt text to images

Accessibility

• Use semantic headings (h1, h2, h3)
• Provide alt text for images
• Ensure sufficient color contrast
• Test with screen readers

Bulk Operations

Updating Multiple Files

Use scripts for bulk operations:

# Find all draft posts
grep -r "draft: true" src/content/blog/

# Update frontmatter in multiple files
find src/content -name "*.mdx" -exec sed -i '' 's/draft: true/draft: false/g' {} +

Content Migration

When migrating content:

1. Export from old system
2. Convert to MDX format
3. Add required frontmatter
4. Validate with schema
5. Test navigation and links

Troubleshooting

Common Issues

Content Not Showing

• Check draft: false in frontmatter
• Verify file extension is .mdx or .md
• Ensure file is in correct language folder

Build Errors

• Validate frontmatter schema
• Check for unclosed tags in MDX
• Verify component imports

Links Broken

• Use relative paths for internal links
• Update links after moving content
• Test all links before deploying

Next Steps

• Working with Collections - Advanced collection features
• Custom Components - Build reusable components
• Search Integration - Add content to search index
• Internationalization - Multi-language content

Need Help?

• Community Forum
• GitHub Discussions
• Support Email