Welcome to Blog Authoring

Published on Wednesday, July 2, 2025

Andrew Lee Rubinger

Lead, Open Source Program Office, Block

This guide will walk you through writing a new blog post.

Writing a Blog Post

Alert: This is a work in progress as we build out the blog system. - ALR

Add Yourself as an Author

Alert: This only needs to be done once, before your first post.

Add Your Avatar

Find a great headshot or other picture you’d like to use as your avatar. Put it in src/assets/blog/avatars:

Add Author Metadata

Open src/content/blog/authors.json in a file editor.

Add an entry for yourself, following the format:

    {
    "alrubinger" : {
        "name": "Andrew Lee Rubinger",
        "title": "Lead, Open Source Program Office, Block",
        "social-github": "ALRubinger",
        "social-linkedin": "alrubinger",
        "social-x": "ALRubinger",
        "avatar" : "alrubinger.jpg"
    }
    ...more
    }

This is the schema:

Property	Description and Notes
`id`	Unique ID for you; this is what you’ll put in the metadata of your blog entries when you write an post.
`author`	The the key of the author in `./src/content/blog/authors.yaml` - defines who wrote the post
`title`	Your job title. What would you say…you do here?
`social-github`	Your GitHub username
`social-LinkedIn`	Your LinkedIn username
`social-x`	Your X, formerly Twitter, username
`avatar`	Location of your avatar image within `src/assets/blog/avatars`; accepts any file format `.jpg`, `.jpeg`, `.png`, or `.gif`.

Make a File for your Blog Post

Create a new .mdx file in /src/content/blog/posts:

In this example, the URL of the blog post will be http(s)://<$domain>/<$baseURL>/blog/my-post. URL Routing is determined by the filename without the .mdx extension. So choose your filename with its target URL in mind.

Add Metadata

At the top of the file you’ve just created, add “frontmatter”, a series of metadata wrapped in --- above and below. For instance:


---
title: Title of my blog post
author: alrubinger
date: 2025-03-22
---

The following properties apply, and they are defined in /src/content/config.ts:

Property	Required	Description and Notes
`title`	✅	The title of the blog post.
`author`	✅	The key of the author in `./src/content/blog/authors.json` – defines who wrote the post.
`date`	✅	Date in ISO 8601 or short-form `YYYY-MM-DD` format. The short form is acceptable because the formatting the docs system uses will drop precision and only show the day and date of the post, leaving off the time.
`excerpt`		A short summary or description of the post, shown in blog indexes. If not provided, an excerpt from the body will be used.
`image`		Path to a hero image for the post. This file should be located in `/src/assets/blog`.
`tags`		An array of tags for the post, e.g. `[“react”, “nextjs”]`.
`readTime`		An estimated amount of time it takes to read this post, e.g. `10 minutes`.

Alert: This section on frontmatter properties will evolve as we build out the schema for blog posts. - ALR

Write your Post

Blog Posts are written in Markdown, and because it’s a full MDX format, this supports all dynamic content available to Astro or any of the rest of the docs system as shown in the examples.