---
globs: *.md
description: Guidelines for authoring blog posts, research articles, and other markdown content
---

# Content Authoring Guidelines

## Frontmatter Requirements
All markdown files must include frontmatter with at minimum:
```yaml
---
title: "Your Title Here"
---
```

### Optional Frontmatter Fields
- `description: "Brief description for SEO and previews"`
- `tags: ["tag1", "tag2", "tag3"]` - For categorization
- `draft: true` - To exclude from build (removed by RemoveDrafts plugin)
- `aliases: ["alternative-url"]` - For URL redirects

## Content Structure Best Practices

### File Organization
- **Blog posts**: Place in `content/blog/` with descriptive filenames
- **Research**: Use `content/research/` for academic/technical papers  
- **Release notes**: Follow pattern in `content/releases/` with date-based naming
- **Quick notes**: Use `content/notes/` for shorter thoughts and observations

### Asset References
- Store images and media in `content/assets/`
- Reference assets relatively: `![Description](../assets/image-name.png)`
- Use descriptive filenames for assets (avoid spaces, use hyphens)
- Optimize images for web (prefer .webp for photos, .png for diagrams)

### Writing Style
- Use clear, descriptive headings (## and ###)
- Include code blocks with proper language specification:
  ```typescript
  // Your code here
  ```
- For mathematical content, use LaTeX syntax with $ for inline math and $$ for blocks
- Link to other content using wikilink syntax: `[[Other Page Title]]`

### Content Types

#### Blog Posts
- Should tell a complete story or explain a concept thoroughly
- Include relevant diagrams or code examples
- Consider adding a brief description for better discoverability

#### Research Articles  
- Follow academic formatting conventions
- Include methodology, results, and conclusions sections
- Reference external papers and sources appropriately

#### Release Notes
- Follow existing date-based naming convention (e.g., "Release Notes MM.DD.YY.md")
- Include version numbers and brief feature summaries
- Categorize changes (New Features, Bug Fixes, Improvements)

#### Notes
- Can be brief thoughts, observations, or work-in-progress ideas
- Don't need to be complete articles
- Good for capturing insights that might become full posts later

## Markdown Extensions
The site supports:
- GitHub Flavored Markdown (tables, task lists, strikethrough)
- Obsidian-style wikilinks `[[Page Name]]`
- Math via KaTeX (`$inline$` and `$$block$$`)
- Syntax highlighting for code blocks
- Callouts (follow Obsidian syntax)

## SEO Considerations
- Use descriptive, unique titles
- Include meta descriptions when appropriate
- Use proper heading hierarchy (h1 → h2 → h3)
- Internal linking helps with site navigation and SEO