Sample GitHub Blog Repository

This is a reference repository showing the expected structure for a GitHub-based blog that works with the Waldium GitHub CMS integration.

Repository Structure

.
├── README.md
└── _posts/
    ├── getting-started.md
    ├── example-post-with-images.md
    ├── advanced-features.md
    └── welcome.md

Required Structure

_posts/ Directory

All blog posts must be placed in the _posts/ directory at the root of your repository.

File Naming

• Use lowercase with hyphens: my-blog-post.md
• Supported extensions: .md or .mdx
• The filename (without extension) becomes the URL slug

Example: _posts/getting-started.md → URL: /posts/getting-started

Frontmatter Format

Each markdown file must start with YAML frontmatter between --- delimiters:

---
title: "Your Post Title"
date: "2024-01-15"
excerpt: "A short description that appears in post listings"
tags: ["tag1", "tag2"]
categories: ["category1"]
coverImage: "/images/cover.jpg"
author:
  name: "Author Name"
  picture: "/images/author.jpg"
---

Required Fields

• title - Post title (string)
• date - Publication date (ISO 8601 format: "YYYY-MM-DD" or "YYYY-MM-DDTHH:mm:ssZ")

Optional Fields

• excerpt - Short description for listings (string)
• tags - Array of tag strings (string[])
• categories - Array of category strings (string[])
• coverImage - URL or path to cover image (string)
• author - Author information (object)
  • name - Author name (string, required if author is provided)
  • picture - Author avatar URL (string, optional)

Example Posts

See the _posts/ directory for complete examples:

• welcome.md - Basic post with minimal frontmatter
• getting-started.md - Post with tags and categories
• example-post-with-images.md - Post with cover image and author
• advanced-features.md - Post with all frontmatter options

Markdown Content

After the frontmatter, write your post content in standard Markdown:

• Headers (#, ##, ###)
• Lists (ordered and unordered)
• Links and images
• Code blocks
• Blockquotes
• Tables
• And more!

Best Practices

1. Use descriptive filenames: my-awesome-post.md not post1.md
2. Keep frontmatter consistent: Use the same date format, author structure, etc.
3. Use tags wisely: Don't create too many unique tags
4. Write good excerpts: 1-2 sentences that summarize the post
5. Organize with categories: Use categories for broad topics, tags for specifics

Deployment

1. Push your posts to the main or master branch
2. Ensure your GitHub App is connected in the Waldium admin dashboard
3. Select this repository in the Git Settings page
4. Posts will appear on your blog automatically!

Webhook Integration

When you push changes to this repository, the webhook will automatically:

• Detect changed files in _posts/
• Invalidate the cache for affected posts
• Make updates visible immediately on your blog

No need to wait for cache expiration!