mirror of https://github.com/aljazceru/goose.git synced 2025-12-17 14:14:26 +01:00

Files

Angie Jones a05029773d docs: blog readme (#2728 )

2025-05-29 14:56:03 -07:00

4.9 KiB

Raw Blame History

unlisted

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:

![blog cover](your-image.png)

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:

![descriptive alt text](image-name.png)

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.yml in 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

4.9 KiB Raw Blame History