How to Write and Publish a Blog Post on This Site

Blog writing and publishing guide

Follow this practical guide to plan, write, format, and publish a blog post in this Nuxt site's content/blogs directory.

29th Sep 2026

6 min read

writingbloggingnuxt

Writing a useful blog post starts with a clear idea and ends with a careful review. This guide explains how to prepare a post for this site, from choosing a topic to checking its Markdown frontmatter before publishing.

1. Choose one useful topic

Start with a question, problem, lesson, or experience that a reader can learn from. Keep the post focused on one main point. Before drafting, write down:

  • Who the post is for: describe the reader and what they already know.
  • What they will learn: state the practical outcome in one sentence.
  • What evidence you can share: gather examples, steps, code, screenshots, or sources that support the explanation.

If the topic is broad, narrow it. A post about one specific error and its fix is usually more useful than a general overview of an entire technology.

2. Make a simple outline

Organize the explanation in the order a reader needs it. A tutorial might use this structure:

  1. Context: explain the problem and when it happens.
  2. Prerequisites: list anything the reader needs before starting.
  3. Steps: show the solution in a clear, numbered order.
  4. Explanation: describe why the important steps work.
  5. Verification: tell the reader how to confirm the result.
  6. Caveats and takeaway: mention relevant limits and summarize the main lesson.

For an experience report, explain what happened, what you tried, what changed, and what you learned. Choose headings that describe the section instead of relying on generic headings such as “Part 1.”

3. Write for clarity

Use direct language and short paragraphs. Introduce technical terms before relying on them, and prefer concrete examples over abstract claims. Include only details that help the reader understand or apply the point.

When sharing code, use a fenced block with the correct language label:

const greeting = 'Hello, reader'

Explain what a meaningful code example demonstrates, and identify any assumptions. For commands or configuration, show the relevant context and avoid presenting an unverified snippet as a complete solution. Link to primary documentation when readers may need current or deeper details.

4. Add the post to the repository

Create a descriptive, URL-friendly Markdown filename under content/blogs/, for example:

content/blogs/9. how-to-write-a-blog-post.md

The filename contributes to the post URL, so keep it specific and avoid spaces when choosing a new filename. Start the file with all required frontmatter fields:

---
title: 'A practical guide to a focused topic'
date: 29th Sep 2026
description: A concise, complete summary of what readers will learn.
image: /blogs-img/blog9.png
alt: A meaningful description of the post image
ogImage: /blogs-img/blog9.png
tags: [topic, technology]
published: true
---

Use these fields consistently:

  • title is the post title shown to readers.
  • date follows the site's human-readable style, such as 29th Sep 2026.
  • description is a short, complete summary kept on one line.
  • image is the main image URL, rooted under / and backed by a file in public/.
  • alt describes the image for readers using assistive technology. Describe the image, not just the post topic.
  • ogImage is the social sharing image URL; it can use the same image as image.
  • tags is a YAML list of relevant, concise categories.
  • published controls whether the post is public. Set it to false while the post is a draft.

Keep the metadata accurate. Do not claim an image exists unless the corresponding file is present in public/. If you do not have a suitable image yet, prepare one before publishing.

Important: quote titles with colons

YAML treats a colon followed by a space as mapping syntax. Always quote a title that contains a colon, for example:

title: 'Durable Execution: The Problem It Solves and How Temporal Works'

If you leave this value unquoted, the parser may treat it as an object. Nuxt Content can then store the page title as [object Object], which appears literally in the page heading and metadata. After adding a title with punctuation, inspect the parsed content or generated page to confirm it remains the intended string.

Important: use Nuxt Content's actual field mapping

In this repository, Nuxt Content query results put the Markdown title and description in seo.title and seo.description. Other frontmatter fields—date, image, alt, ogImage, tags, and published—are top-level. The built-in top-level title can be object-valued, so passing it directly to Vue can render as [object Object].

When adding or changing blog rendering code, use the shared toBlogCardPost helper in app/utils/blog.ts to map a content result to display fields. Use it on every page that displays a post, including recent posts and the blog detail page. Avoid passing raw query values directly to text, SEO metadata, or OG image components. After the change, inspect the rendered title, description, date, and image and confirm no object values or fallback content appear.

5. Review before publishing

Read the post once for meaning and once for details. Check that:

  • The title, opening, headings, and conclusion all support the same main point.
  • Every step is actionable and appears in the right order.
  • Code, commands, dates, and technical claims are accurate and explained.
  • Markdown fences are closed, links work, and lists render as intended.
  • The frontmatter includes every required field, with valid YAML values.
  • Image URLs point to files in public/, and the alt text is meaningful.
  • The description is complete and published reflects the intended status.

For a Markdown-only change, review the frontmatter and links. If the change affects content structure or rendering, run the site build as well. Keep drafts marked published: false until they are ready for readers.

A reusable checklist

Before publishing, make sure you can answer “yes” to each question:

  • Does the post solve one clear problem or teach one focused lesson?
  • Can a reader follow the explanation without guessing at missing steps?
  • Are examples and claims accurate, with sources where needed?
  • Does the post have complete metadata and a real, accessible image?
  • Have you reviewed the rendered Markdown and publication status?

A well-written post respects the reader's time: it gives enough context to understand the topic, enough detail to act, and a clear way to know what to do next.