OpenBlog Collaborative writing for portfolio and reputation growth

Writing guide

Post .md structure for OpenBlog

Use this structure when you create or improve any post file under content/posts/.

This page explains each metadata field, shows production-ready examples, and helps you avoid common mistakes.

Back to contribution guide Markdown standards

File path and naming

  • Store posts only in content/posts/<category>/<post-file>.md.
  • Use lowercase and hyphens for category and file names.
  • Keep one post per file. Nested folders are not supported inside categories.
content/posts/networking/how-dns-works.md

Recommended full template

---
title: How DNS Works
description: Learn how DNS converts domain names to IP addresses with practical examples.
date: 2026-03-16
thumbnail: https://images.example.com/dns-cover.jpg
thumbnailAlt: Network map with DNS lookup arrows
tags:
  - networking
  - dns
  - internet
featured: false
draft: false
lang: en
# translateOf: how-dns-works-fa.md
---

Start with a short intro that explains the problem and what the reader will learn.

## How DNS lookup works

Explain the flow clearly and add at least one practical example.

For example, resolving openblog.cc usually goes through:
1. Recursive resolver
2. Root and TLD nameservers
3. Authoritative nameserver

```bash
dig openblog.cc
nslookup openblog.cc
```

Metadata field reference

Field Required What it does Example
title Yes Main post title used on cards, post page, and SEO tags. How DNS Works
description Yes Short summary used in listings, previews, and meta description. Learn DNS lookup flow with examples.
date Yes Publishing date used for sorting and display. Prefer YYYY-MM-DD. 2026-03-16
thumbnail No Cover image URL shown in cards and post header. https://images.example.com/dns.jpg
thumbnailAlt No Accessible alt text for the thumbnail image. DNS lookup diagram
tags No Topic keywords for filtering and tag pages. String or YAML array. [networking, dns]
draft No When true, the post is hidden from public pages. false
featured No Highlights the post in featured UI areas. true
lang No Language code used for badges and page language metadata. en, fa, de
translateOf No Links a translation to the source post in the same category folder. how-dns-works.md

Minimal valid template

---
title: HTTP Caching Basics
description: Understand browser and CDN caching in simple terms.
date: 2026-03-16
---

Intro paragraph.

## Main section

Explain with one simple example.

Translation metadata

---
title: How DNS Works (FA Translation)
description: Persian translation of the DNS guide.
date: 2026-03-16
lang: fa
translateOf: how-dns-works.md
---

Use a relative file name in the same category folder for translateOf.

Scoring note for metadata improvements

If your merged PR improves metadata on an existing post, it receives +10 points via the fix-metadata scoring rule.

This applies even when the post was originally written by another contributor.

Common mistakes to avoid

  • Do not place posts directly under content/posts/ (category folder is required).
  • Do not use absolute paths in translateOf.
  • Do not reference a translation target outside the same category folder.
  • Avoid vague descriptions like This post is about...; write concrete summaries.