Authoring Basics: Modules, Front Matter, and Sync

beginner 8 minutes
authoring content-creation markdown

Welcome to the first module in the Course Authoring series! This module will teach you the core concepts of creating learning content for the Hedgehog Learn platform.

Understanding Module Structure

Every learning module in Hedgehog Learn follows a consistent structure:

content/modules/your-module-slug/
├── README.md       # Main content file with front matter
└── meta.json      # Optional: prerequisites and learning objectives

The README.md File

The README.md file contains two essential parts:

  1. Front Matter - YAML configuration at the top
  2. Markdown Content - The actual learning material

Front Matter Configuration

Front matter is a YAML block at the beginning of your README.md file, enclosed by triple dashes (---). Here's a complete example:

---
title: "Your Module Title"
slug: "your-module-slug"
difficulty: "beginner"
estimated_minutes: 10
tags:
  - tag1
  - tag2
description: "A brief description for SEO and previews"
order: 1
---

Required Front Matter Fields

  • title: The display name of your module (shown in the UI)
  • slug: URL-friendly identifier (lowercase, hyphens only)
  • difficulty: One of: beginner, intermediate, or advanced
  • estimated_minutes: How long the module takes to complete
  • tags: Array of relevant keywords for filtering
  • description: Brief summary (used for SEO meta description)

Optional Front Matter Fields

  • order: Display order in lists (defaults to 999)
  • version: Content version (e.g., "v1.30")
  • validated_on: Date last tested (e.g., "2025-10-13")
  • social_image: URL to social preview image
  • archived: Set to true to hide from main listings

Writing Markdown Content

After the front matter, write your content using standard GitHub-flavored markdown:

# Main Title (automatically stripped by sync)

## Section Heading

Regular paragraph text with **bold** and *italic* formatting.

### Subsection

- Bullet point 1
- Bullet point 2

1. Numbered list item
2. Another item

```bash
# Code blocks with syntax highlighting
kubectl get pods

Blockquotes for important notes

Links work as expected.


### Code Blocks Best Practices

Use fenced code blocks with language identifiers for syntax highlighting:

````markdown
```bash
# Bash commands
npm run sync:content

// JavaScript code
const module = { title: "Example" };

# YAML configuration
key: value


## The Sync Process

Once your module is ready, sync it to HubDB using the sync command:

```bash
npm run sync:content
```

### What Happens During Sync

1. **Discovery**: Script scans `content/modules/` directory
2. **Parsing**: Reads front matter and markdown content
3. **Conversion**: Converts markdown to HTML
4. **Upsert**: Creates or updates HubDB rows
5. **Publish**: Publishes the HubDB table

### Environment Variables

The sync process respects these environment variables:

- `SYNC_DELETE_MISSING`: Set to `false` to prevent deleting removed modules
- `SYNC_STRIP_LEADING_H1`: Set to `false` to keep the first H1 heading
- `SYNC_ARCHIVE_DIR`: Location of archived content (default: `content/archive`)
- `SYNC_ARCHIVE_STRATEGY`: Either `tag` (soft archive) or `delete` (hard delete)

### Safe Sync Command

To sync new content without deleting existing modules:

```bash
SYNC_DELETE_MISSING=false npm run sync:content
```

## Module Naming Conventions

Follow these conventions for consistency:

- **Slugs**: Use lowercase with hyphens (e.g., `authoring-basics`)
- **Titles**: Use title case with descriptive names
- **Directory names**: Must match the slug exactly
- **File names**: Always use `README.md` (case-sensitive)

## Testing Your Module

After syncing, verify your module:

1. Check the HubDB table in HubSpot
2. View the module detail page on the live site
3. Verify all formatting renders correctly
4. Test code blocks for proper syntax highlighting
5. Check that tags and metadata are accurate

## Common Mistakes to Avoid

- ❌ Missing required front matter fields
- ❌ Using uppercase or spaces in slugs
- ❌ Forgetting the closing `---` in front matter
- ❌ Not running `npm run build` before sync (sync script handles this)
- ❌ Using unsupported markdown syntax

## Optional: meta.json File

For advanced modules, create a `meta.json` file alongside `README.md`:

```json
{
  "prerequisites": [
    {
      "module_slug": "prerequisite-module",
      "title": "Prerequisite Module Title"
    }
  ],
  "learning_objectives": [
    "Understand core concepts",
    "Apply knowledge in practice",
    "Create your own modules"
  ]
}
```

This data is serialized as JSON and stored in the `prerequisites_json` column of HubDB.

## Next Steps

Now that you understand the basics of module authoring, you're ready to:

- Learn about [media and metadata](/module/authoring-media-and-metadata)
- Explore [assembling courses](/module/authoring-assembly-courses)
- Master [QA and troubleshooting](/module/authoring-qa-and-troubleshooting)

## Resources

- [Markdown Guide](https://www.markdownguide.org/)
- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
- [YAML Specification](https://yaml.org/spec/)
- [HubDB Documentation](https://developers.hubspot.com/docs/api/cms/hubdb)