| unlisted |
|---|
| true |
Writing Blog Posts for goose
This guide explains how to write and structure blog posts for the goose documentation site.
Getting Started
- Clone the goose repository:
git clone https://github.com/block/goose.git
cd goose
- Install dependencies:
cd documentation
npm install
Directory Structure
Blog posts are organized by date using the following format:
YYYY-MM-DD-post-title/
├── index.md
└── images/
Example:
2025-05-22-llm-agent-readiness/
├── index.md
└── llm-agent-test.png
Frontmatter
Each blog post must begin with YAML frontmatter that includes:
---
title: Your Blog Post Title
description: A brief description of your post (1-2 sentences)
authors:
- your_author_id
---
The authors field should match your ID in the authors.yml file. Multiple authors can be listed. More info on authors.
Header Image
After the frontmatter, include a header image using Markdown:
The header image should be:
- Relevant to the post content
- High quality (recommended dimensions: 1200 x 600 px)
- Stored in the post's directory
- Named descriptively
Content Structure
Introduction
Start with 1-2 paragraphs introducing the topic before the truncate tag. This will be what's shown on the blog index page.
Truncate Tag
Add the truncate tag after your introduction to create a "read more" break:
<!-- truncate -->
Headers
Use headers to organize your content hierarchically:
#(H1) - Used only for the post title in frontmatter##(H2) - Main sections###(H3) - Subsections####(H4) - Minor sections (these will not show on the right nav bar)
Code Blocks
Use fenced code blocks with language specification:
```javascript
// Your code here
```
Images
Include additional images using Markdown:
Social Media Tags
At the end of your post, include the following meta tags for social media sharing:
<head>
<meta property="og:title" content="Your Blog Post Title" />
<meta property="og:type" content="article" />
<meta property="og:url" content="https://block.github.io/goose/blog/YYYY/MM/DD/post-slug" />
<meta property="og:description" content="Your blog post description" />
<meta property="og:image" content="https://block.github.io/goose/assets/images/your-image.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta property="twitter:domain" content="block.github.io/goose" />
<meta name="twitter:title" content="Your Blog Post Title" />
<meta name="twitter:description" content="Your blog post description" />
<meta name="twitter:image" content="https://block.github.io/goose/assets/images/your-image.png" />
</head>
Author Information
To add yourself as an author:
- Edit
authors.ymlin the blog directory - Add your information following this format:
your_author_id:
name: Your Full Name
title: Your Title
image_url: https://avatars.githubusercontent.com/u/your_github_id?v=4
url: https://your-website.com # Optional
page: true
socials:
linkedin: your_linkedin_username
github: your_github_username
x: your_twitter_handle
bluesky: your_bluesky_handle # Optional
Best Practices
-
Writing Style
- Use clear, concise language
- Break up long paragraphs
- Include code examples where relevant
- Use images to illustrate complex concepts
-
Technical Content
- Include working code examples
- Explain prerequisites
- Link to relevant documentation
- Test code snippets before publishing
-
Formatting
- Use consistent spacing
- Include alt text for images
- Break up content with subheadings
- Use lists and tables when appropriate
-
Review Process
- Proofread for typos and grammar
- Verify all links work
- Check image paths
- Test code samples
- Validate frontmatter syntax
Previewing Your Blog Post
To preview your blog post locally:
- Ensure you're in the documentation directory:
cd documentation
- Start the development server:
npm start
- Open your browser and visit:
http://localhost:3000/goose/blog
The development server features:
- Hot reloading (changes appear immediately)
- Preview of the full site navigation
- Mobile responsive testing
- Social media preview testing
If you make changes to your blog post while the server is running, the page will automatically refresh to show your updates.
Troubleshooting Preview
If you encounter issues:
- Make sure all dependencies are installed:
npm install
- Clear the cache and restart:
npm run clear
npm start
- Verify your frontmatter syntax is correct (no tabs, proper indentation)
- Check that all image paths are correct relative to your post's directory