Writing a blog post

This guide explains how to write up a blog post following a walkthrough. For information on suggesting topics or volunteering to teach, see CONTRIBUTING. For the writing-style rules and review checklist applied to drafts (and used by AI coding agents helping with a write-up), see AGENTS.md in the repository root.

File Structure

Blog posts are written in Quarto Markdown and stored in the following locations:

  • Blog posts: posts/YYYY-MM-DD-title-of-walkthrough/index.qmd
  • Images: posts/YYYY-MM-DD-title-of-walkthrough/images/
  • Other assets: posts/YYYY-MM-DD-title-of-walkthrough/asset-name/

Step-by-Step Guide

  1. Create a new branch from main:

    git checkout -b walkthrough/descriptive-name

  2. Create your post file in the posts directory with the naming convention:

    YYYY-MM-DD-title-of-walkthrough/index.qmd

    Example: 2024-01-15-intro-to-docker/index.qmd

  3. Add front matter at the top of your Markdown file:

    index.qmd
    ---
title: "Introduction to Docker"
date: 2024-01-15
date-modified: last-modified
draft: true
author:
  - Author Name
  - Coauthor Name
categories: [ "Docker", "Containers", "Package management" ]
---

    draft: true keeps a post out of the published site’s listings while it’s still being written or hasn’t been scheduled yet — Quarto still renders it in quarto preview. Remove the draft field once the session has actually been given and the content and date are settled, not just once the writing is finished.

  4. Write your content using Markdown. Include:

    • Brief introduction
    • Step-by-step instructions
    • Code examples
    • Screenshots or diagrams (if applicable)
    • Key takeaways
    • Further resources

  5. Add images to posts/YYYY-MM-DD-title-of-walkthrough/images/ and reference them:

    ![Alt text](images/screenshot.png)

  6. Add assets to ignore list if Quarto would try to render them:

    If you include assets that Quarto might try to render (e.g., example Quarto projects, quarto page examples), add them to the ignore list in _quarto.yml:

    _quarto.yml
    project:
type: website
render:
  - "*.qmd"
1  - "!posts/2024-05-14-quarto-to-confluence/quarto-example*/"
  - "!posts/YYYY-MM-DD-your-post/assets-to-ignore/"
    1
    Prefix folders with ! to exclude them. Wildcards (*) are supported.

    Note: Most posts won’t need this step - only add if you encounter rendering issues.

  7. Preview locally:

    quarto preview # or `pixi run preview`

    quarto preview will automatically open the rendered preview in your browser.

  8. Submit a Pull Request:

    • Push your branch to GitHub
    • Open a PR with a clear description
    • Link to the related Issue (e.g., “Closes #42” in the PR description)
    • Request review from team members

  9. Address feedback and merge once approved.

Writing Tips

  • Keep it concise and focused — a post supports a ~30-40 minute talk with a live demo, it’s not a reference manual for the tool
  • A post should stand alone: don’t assume the reader has seen another still-unpublished walkthrough, and don’t forward-reference content later in the same post
  • Use code blocks with syntax highlighting and code annotation
  • Include practical examples
  • Add links to relevant documentation
  • Consider adding a “Prerequisites” section if needed
  • See existing posts in the posts/ directory for examples and inspiration
  • Check the Quarto documentation for advanced formatting options
  • See AGENTS.md for the fuller style and review checklist (prose style, scope, and independence rules with their reasoning)