Introduction

Managing your blog content as code brings version control, reviews, automation, and repeatability. Hashnode supports GitHub-powered publishing: you push Markdown files with special front matter, Hashnode ingests them, and your post appears (or updates) automatically.

This article is a reference point for who wants to manage a solid process flow in their Hashnode blogging solution. It explains structure, metadata, safe workflows, and an alternative asset hosting via GitHub Pages (for body images only) so you avoid accidental duplicate posts or broken slugs while keeping images portable.

Process Flow

Below is the end-to-end process from local authoring to publication:

Key stages:

1. Author locally using Markdown (with valid front matter) and any images.
2. Commit & push to the connected repository branch.
3. Hashnode sync service polls / is triggered and parses front matter to qualify the post.
4. If slug already exists (same path or moved) → update; otherwise → create.
5. Publication updated; cover image is served from Hashnode CDN; optional post assets can live on GitHub Pages.

Requirements

• Hashnode account + publication (or personal blog).
• A GitHub repository (public or private; if private you must grant access during setup).
• Each post: a .md file with valid front matter section --- ... --- preceding body content.

GitHub Repository Structure

You can organize posts in dated folders (e.g. 2025/first-post.md) or topical folders. The path participates in update logic: changing ONLY the path updates existing post; changing BOTH path and slug produces a new post. In this example structure I'm partitioning by year but you may further partition based on the overall post distribution over time or another dimension relevant to your project.

Example:

/2025/
  hashnode.md   # this article
  another-post.md
/assets/        # optional local image sources for body (NOT cover)

Hashnode Post Definition

In this section we walk thought the elements required to author a valid post for Hashnode ingestion and how we use different parameters to manage the post-flow.

Front Matter Essentials

Required fields: title, slug, tags, domain.

Optional but useful:

• subtitle (teaser under title)
• cover (MUST be a URL from the Hashnode image uploader/CDN ONLY)
• saveAsDraft: true (keep unpublished until review)
• enableToc: true (auto table of contents)
• ignorePost: true (skip ingestion; keep file in repo)
• canonical (if cross-posting from original source)
• publishAs (team publications)

Refer to the public instruction spec (hashnode authoritative documentation at the moment I write this post): instructions.txt

Slug & Update Rules

Hashnode identifies posts with a combination of slug + path behavior:

• Same slug, same (or moved) path => update existing post.
• Change ONLY slug => existing post updated to new slug (old URL handled by Hashnode redirect logic).
• Change ONLY path => post updated; slug stays stable.
• Change BOTH slug & path => treated as NEW post (original remains unless deleted manually in dashboard).

Draft Workflow

1. Start with saveAsDraft: true while iterating.
2. Remove the line (or set false) when ready to publish.
3. Subsequent edits (without re-adding saveAsDraft) update the live post.

Ignoring a File

Set ignorePost: true to prevent ingestion (useful for templates, notes, or WIP outlines). Remove or set to false later to activate.

Tags

Provide up to 5 valid tag slugs (lowercase). They influence discovery. Research tag list (Hashnode support repo) before finalizing. Avoid stuffing unrelated tags.

Suggested Authoring Flow

1. Copy the instruction spec contents into a new file as a starting template.
2. Fill required metadata (upload cover immediately to avoid forgetting).
3. Decide body image hosting; add assets accordingly.
4. Write content; commit (e.g., feat(post): add hashnode sync foundation article).
5. Review via PR (optional).
6. Merge & push; verify post + images.
7. Iterate; optimize SEO fields.

Minimal Template

---
title: Your Title Here
slug: your-slug-here
tags: hashnode, github
domain: your-domain.hashnode.dev
cover: https://cdn.hashnode.com/res/hashnode/image/upload/...
saveAsDraft: true
---

# Heading
Content...

Common Pitfalls

Images & Media

When managing media we must make a distinction between the cover of our post:

• Cover Image: MUST come from Hashnode's uploader (https://hashnode.com/uploader). Hashnode requires cover images to be served from its own CDN.
• Post Images: May use either Hashnode CDN (recommended for simplicity) OR any publicly accessible, reliable external host (e.g. GitHub Pages). External body images allow version control and custom domains, but you must self-optimize them.

Referencing Images in your Post

• Hashnode CDN: ![Alt text](https://cdn.hashnode.com/res/hashnode/image/upload/v1756828007758/jJIjjUFi_.png)
• GitHub Pages: ![Alt text](https://<username>.github.io/<repo>/assets/diagram.png)
• Custom Pages domain: ![Alt text](https://asset.andresantacroce.com/2025/hashnode/flow.svg) after DNS + Pages config.

Always include descriptive alt text for accessibility and SEO.

Choosing Hosting Options

GitHub Pages Setup

Full official guide available at this link: GitHub Pages Quickstart

I would highly recomment this option if you want to keep your images versioned alongside your posts and avoid relying on third-party image hosts that may change policies or go down. Follow these key steps to manage the setup:

1. Branch Strategy: Serve from main root or /docs folder.
2. Create assets/ folder; commit images (avoid very large originals—optimize first).
3. Enable Pages: Settings > Pages > "Deploy from a branch" (select branch + folder) > Save.
4. (Optional) Custom domain + CNAME + DNS (add CNAME file + DNS record).
5. Wait for deployment; verify an asset URL loads.
6. Embed URLs in your Markdown body.

Directory Example

/2025/hashnode.md
/assets/2025/image-1.svg
/assets/2025/image-2.svg

Conclusion

With this structure, blogging becomes repeatable and auditable. Posts are code; reviews catch errors early; publishing is a push away. My future articles will build on this baseline.

Happy writing!