mirror of
https://github.com/jackyzha0/quartz.git
synced 2025-12-19 10:54:06 -06:00
79 lines
2.7 KiB
Plaintext
79 lines
2.7 KiB
Plaintext
---
|
|
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: ``
|
|
- 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 |