Each blog post must begin with YAML frontmatter that includes:
---title:Your Blog Post Titledescription: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><metaproperty="og:title"content="Your Blog Post Title"/><metaproperty="og:type"content="article"/><metaproperty="og:url"content="https://block.github.io/goose/blog/YYYY/MM/DD/post-slug"/><metaproperty="og:description"content="Your blog post description"/><metaproperty="og:image"content="https://block.github.io/goose/assets/images/your-image.png"/><metaname="twitter:card"content="summary_large_image"/><metaproperty="twitter:domain"content="block.github.io/goose"/><metaname="twitter:title"content="Your Blog Post Title"/><metaname="twitter:description"content="Your blog post description"/><metaname="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 Nametitle:Your Titleimage_url:https://avatars.githubusercontent.com/u/your_github_id?v=4url:https://your-website.com # Optionalpage:truesocials:linkedin:your_linkedin_usernamegithub:your_github_usernamex:your_twitter_handlebluesky: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
