โฆ Contributor guide ยท Blogs
Write for recode hive: publish your first blog post
From idea to published post in 11 steps. We care about quality over quantity: real experience, real screenshots, and clear writing.
- โฑ 2 to 4 hours, mostly writing
- 11 steps
- Reviewed by maintainers
Before you start
You need
- Node.js 18 or higher, Git and VS Code
- The project running locally. Not yet? Follow the First-time setup guide first.
- A topic you have real experience with
What gets a post accepted
- An assigned issue before you start
- Your own screenshots and lessons
- A summary at the top and a FAQ at the end
- 5 external and 5 internal links
1. Raise an issue and get assignedโ
Open a new issue on the repo using the Documentation update category. Describe the post you want to write and why it is useful.
Do
- Write from real experience: a project you built, a bug you fixed, a tool you compared
- Plan real screenshots from your own setup
- Wait until a maintainer assigns the issue to you
Don't
- Pick generic "Intro to X" topics that already exist everywhere
- Start writing before you are assigned
- Paste AI-generated text without your own experience
2. Create a new branchโ
Never commit to main. Create a branch named after your post:
git checkout -b blog/intro-to-docker
Not set up yet? Fork, clone and install the project first with the First-time setup guide.
3. Add yourself as an authorโ
Add an entry to blog/authors.yml so your name, photo and links appear on the post. Copy this and replace every value with your own:
your-github-username: name: Your Name title: Your role, for example Data Engineer url: https://github.com/your-github-username image_url: https://github.com/your-github-username.png socials: linkedin: your-linkedin-id
The key at the top is your author id. You will use it again in the authors field of your post.
4. Create the post folderโ
Each post lives in its own folder with its images next to it:
Use lowercase words joined by hyphens for the folder name. It becomes the post's URL.
5. Write the frontmatterโ
The frontmatter is the block at the very top of index.md. It sets the title, author, tags and search description.
--- title: "How I set up X in 10 minutes" authors: [your-github-username] tags: [docker, devops] date: 2026-10-22 description: One or two sentences that make someone want to click. draft: false ---
| Field | Required | What to write |
|---|---|---|
title | Yes | The full post title. Check what people search for before you pick it. |
authors | Yes | Your author id from blog/authors.yml, in square brackets. |
tags | Yes | Two to four topics, for example [docker, devops]. |
date | Yes | Publication date as YYYY-MM-DD. |
description | Yes | One or two sentences, under 160 characters. It shows in search results. |
draft | Yes | false to publish, true to hide the post. |
canonical_url | No | Leave it out. Add it only if the post was published on another site first. |
6. Write the contentโ
Keep paragraphs short and explain things the way you would to a friend. Every post needs these parts:
- Bulleted summary3 to 5 bullets right after the intro. Put
<!-- truncate -->after it so only this shows on the blog list. - The main contentReal steps, real screenshots, and your own lessons. More text than code.
- FAQ section3 to 5 questions people actually search for.
Use admonitions to highlight important points:
:::tip Use tips for shortcuts and good habits. ::: :::caution Use cautions for things that can break. :::
Quality bar. Accepted posts include at least 5 links to other sites and 5 links to other recode hive pages, use descriptive image names, and end with a FAQ.
7. Add screenshots and a bannerโ
Name images in lowercase with hyphens and a number, in the order they appear:

Always write alt text that describes the image. It helps screen readers and Google Images. Compress images with Squoosh or TinyPNG to stay under 500 KB.
Tools like Snagit make annotated screenshots easy. See this guide for the image quality we aim for.
8. Add your post to the blog listโ
Add an entry to src/database/blogs/index.tsx so your post appears on the blog page:
{
id: 22,
title: "How I set up X in 10 minutes",
image: "/img/blogs/your-blog-title.png",
description: "One or two sentences about the post.",
slug: "your-blog-title",
date: "2026-10-22",
readingTime: 8,
authors: ["your-github-username"],
category: "DevOps",
tags: ["docker", "devops"],
},Use the next free id and the same slug as your folder name. Put the banner in static/img/blogs/. readingTime is in minutes and tags is optional. Every other field is needed for the blog card.
9. Preview your postโ
npm run start
Open localhost:3000/blog and check your post: images load, links work, the summary shows above "Read more", and the FAQ is there.
10. Commit and pushโ
git add . git commit -m "blog: add <post title>" git push origin <branch>
Replace <branch> with the branch from step 2, for example blog/intro-to-docker.
11. Open a pull requestโ
On GitHub, open your fork and click Compare & pull request. The base must be recodehive/recode-website on main.
- Title:
blog: <post title> - Link your issue with
Closes #<issue>. - Add a screenshot of the post running on localhost.
Keep your fork up to dateโ
Before you start a new post, pull in the latest changes from recode hive so your branch does not fall behind:
git remote add upstream https://github.com/recodehive/recode-website.git git fetch upstream git checkout main git merge upstream/main
You only need the first line once.
Final checklistโ
Previous version of this guide
This guide walks you through everything you need to write and publish a blog post on recode hive, heads-up for you there is a lot of steps, our idea is not about quantity, lets focus on the quality of the post you write the best one will be eligible for GitHub Sponsorship.
- ๐ฆ Node.js (v18 or later)
- ๐ง Git
- ๐ป VS Code or your preferred editor
- Refer the welcome page to install and setup the repository in your local system. Check here
Step 1: Raise a New issue on GitHubโ
Head to the GitHub issue on this repository, raise a new issue under documentation update.
- Few things to remember, don't raise random generic topics.
- Write from real experience, try to include real dashboard pictures, no copy paste articles.
- You can generate AI pictures, but need to be edited any tools like Canva.
- Your article must teach something official documentation does not. Means no Intro to X or What is X.
- Start working on Issue When its assigned to you by @sanjay-kv or any Maintainer. ref step 4.
Just follow the steps on forking the repositories and installing the dependencies on your local repository, if you dont know refer the steps 2 to 6 on welcome page.โ
Step 5: Create a New Branchโ
Open your code editor and head into terminal and check current branch
Never commit directly to main. Create a dedicated branch for your blog post:
git checkout -b blog/your-blog-title
the best practice, Use a short, descriptive name for example blog/intro-to-docker or blog/react-hooks-guide.
Step 6: Add your name to Author list : optionalโ
If you are first time contributing to blog section, add yourself as author, this gives you good visibility on Google search and better career opportunities. We use docusaurus for documentation.
Open your code editor and head into sidebar and expand the blog folder
and open the file authors.yml. Refer the below image and copy paste the code into the yml as shown.
Replace my name with your name and respective website links of yours.
sanjay-kv:
name: Sanjay Viswanathan
title: Founder at recode hive
url: https://nomadbrains.dev
image_url: https://avatars.githubusercontent.com/u/30715153?v=4
email: sanjay@recodehive.com
page: true # Turns the feature on
description: >
I'm a Software Engineer turned into a Data Engineer and Program Manager๐, ๐ Google ML Facilitator & Ex- GitHub CE who delivered 100+ talks on ML and open source and developer advocacy at various events and platforms.
socials:
x: https://x.com/nomadbrainsdev
linkedin: sanjay-k-v
github: sanjay-kv
stackoverflow: 8332327
instagram: nomadbrains.dev
newsletter: https://recodehive.substack.com
bluesky: sanjaykv.bsky.social
The your-author-id value must exactly match what you put in the authors field of your frontmatter.
Step 7: Create the Blog Folder and Fileโ
All blog posts live inside the blog/ directory. Each post gets its own folder.
Folder structure:
blog/
โโโ your-blog-title/
โโโ index.md โ your blog content
โโโ assets/ โ screenshots and images (optional png or jpeg)
โโโ cover.png
โโโ step-01.png
you can manually Create the folder and file or use below code:
mkdir -p blog/your-blog-title/assets
touch blog/your-blog-title/index.md
- Step 7
- Step 8
Step 9: Write the Frontmatterโ
Open blog/your-blog-title/index.md and add the following frontmatter at the very top of the file:
Copy paste the below code into your index.md file you created, then before writing we slowly change the title and details over here. first thing you need to match the author ID same as you created in authors.yaml file.
- Step 9
- Step 10
- Step 11
- Step 12
- Step 13
Keep the structure of the meta block as shown. Change only its values (title, description and URLs) to match your post and folder name.
Do npm run build and complete the build to see everything works fine.
Do npm run serve or npm start and open local host to see the local changes you made.
Do search this in local host http://localhost:3000/your-blog-canonical-url
title: "Google Changed Workspace Icon after 6 years"
authors: [sanjay-kv]
sidebar_label: "Google Changed Workspace Icon after 6 years"
tags: [google, icons]
date: 2026-05-21
description: Google Changed Workspace Icon after 6 years, What Changed, What Did Not, and Why It Took Six Years
draft: false
meta:
- name: "robots"
content: "index, follow"
- property: "og:title"
content: "Google Changed Workspace Icon after 6 years"
- property: "og:description"
content: "Google Just Changed Every Workspace Icon: What Actually Changed and Why It Took Six Years."
- property: "og:type"
content: "article"
- property: "og:url"
content: "https://www.recodehive.com/blog/google-icon-update"
- property: "og:image"
content: "./images/cover.png"
- name: "twitter:card"
content: "summary_large_image"
- name: "twitter:title"
content: "Google Just Changed Every Workspace Icon: What Actually Changed and Why It Took Six Years"
- name: "twitter:description"
content: "Google Changed Workspace Icon after 6 years"
- name: "twitter:image"
content: "./images/cover.png"
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<!-- truncate -->
---
Last week I clicked Google Meet when I meant to click Google Calendar. Again.
**What you'll learn in this post:**
- How to set up X from scratch
- How to configure Y for production
- Common pitfalls and how to avoid them
---
## The Problem That Started in 2020
To understand why this redesign matters, you have to go back to October 2020 when Google rebranded G Suite to Google Workspace.
---
## What Changed in 2026
The new icons do one thing that the 2020 redesign refused to do: they let each app look different from the others.
---
## Why Google Is Doing This Now
Two reasons. One practical, one strategic.
---
## What the Internet Actually Thinks
Reactions are split, which is predictable and honestly fair.
---
## Does It Actually Solve the Problem?
Yes. Partially.
---
## What to Watch Next
The rollout is live but incomplete as of today. Google I/O 2026 this week is the most likely venue for a formal announcement with a full rollout timeline. If you are not seeing the new icons in your web launcher yet, they are coming within days based on current reports.
---
## The Bigger Picture
Google changing its icons is a small thing in isolation. But it is interesting as a signal.
---
**About the Author**
Sanjay is a Data Engineer focused on building modern data platforms and writing about technology at RecodeHive. He writes about data engineering, cloud architecture, and the tech decisions that actually affect people's daily work.
<GiscusComments/>
| Field | Description |
|---|---|
title | The full title displayed at the top of the post and in search results, Make sure you do research and SEO analysis before proceeding with title |
authors | Your author ID from blog/authors.yml (see Step 6) |
sidebar_label | Short label shown in navigation sidebars |
tags | Comma-separated list of relevant topic tags |
date | Publication date in YYYY-MM-DD format |
description | SEO meta description (keep under 160 characters) |
draft | Set to true to hide the post; false to publish |
canonical_url | Leave blank unless cross-posting from another site |
Step 10: Write Your Blog Content : Guidelinesโ
Now here comes the crucial part, it doesnt matter how it get start, but you gotta finish it as good quality work. Open the below taps to find most common errors and guidelines for beautification
- Formatting Guidelines
- Add code blocks
- Query + Output: Use Tabs
You have already copied this code before, im just explaining what it is. So you know what you doing ๐ฅ.
After the closing --- of your frontmatter, add the <!-- truncate --> comment. Everything above this comment becomes the preview shown on the blog listing page; everything below is the full post.
---
...frontmatter...
---
<!-- truncate -->
Your introduction paragraph goes here. This will appear as the preview on the blog index page.
## Section Heading
Body content continues here...
Formatting Guidelinesโ
Use ## and ### headings to structure your content.
Bulleted Summary Section (Required)โ
Every technical explanation blog eg: how to run codeql on GitHub must begin with a bulleted summary right after the intro paragraph. This helps readers quickly understand what they'll learn.
**What you'll learn in this post:**
- How to set up X from scratch
- How to configure Y for production
- Common pitfalls and how to avoid them
Named Code Blocks (Required)โ
Always label code blocks with a filename so readers know exactly what file they are editing: Once you copy paste this block it will appear exactly like this for the users.
```java title="Sample.java"
public class Hello {
public static void main(String[] args) {
System.out.println("Hello, world!");
}
}
```
Named Code Blocks (Required when writing technical articles)โ
When showing a database query alongside its output, use a Tabs block so both fit in a single window.
First, import the components at the top of your index.md (after frontmatter, before any content):
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Then structure your query + output like this:
<Tabs>
<TabItem value="SQL Table" label="SQL Table">
```sql title="Friends"
| id | name | username |
|----|-----------------|------------------|
| 1 | John Doe | @johndoe |
| 2 | Jane Smith | @janesmith |
| 3 | Bob Johnson | @bobjohnson |
```
</TabItem>
<TabItem value="SQL Code" label="SQL Code">
```sql title="Creating SQL Tables & db. "
-- creating database
CREATE DATABASE my_database;
-- use the database you created
USE my_database;
-- Create the table
CREATE TABLE friends (
id INT PRIMARY KEY,
name VARCHAR(100),
username VARCHAR(100)
);
-- Insert data into the table
INSERT INTO friends (id, name, username) VALUES
(1, 'John Doe', '@johndoe'),
(2, 'Jane Smith', '@janesmith'),
(3, 'Bob Johnson', '@bobjohnson');
```
</TabItem>
</Tabs>
You can add as many <TabItem> tabs as needed for example separate tabs per subquery type, or one tab per language variant.
See the Tabs example above for the full syntax.
Again a reminder, dont copy from the AI, the whole purpose of we writing this to give some step by step guidelines which AI can't do. Especially from an experienced engineers, it will be easy for new generation coders to start easy with reference ss of every step.
Step 11: Add Screenshots and Bannerโ
Recommended Screenshot Dimensionsโ
| Use Case | Recommended Size |
|---|---|
| Cover / hero image | 1200 ร 630 px (16:9 ratio, also ideal for social sharing) refer the image blocks attached below for samples |
| Full-width step screenshots | 1280 ร 720 px or 1280 ร 800 px |
| UI close-ups / partial screenshots | 800 ร 450 px |
| Maximum file size | 500 KB per image (compress with Squoosh or TinyPNG) |
Use PNG for UI screenshots (crisp text) and JPEG/WebP for photos.
Naming Conventionโ
Use lowercase, hyphen-separated, numbered filenames so they sort correctly and are SEO-friendly. Never use random or auto-generated names. also never leave space on naming, it should be connected with hypen.
assets/
โโโ cover.png
โโโ 01-open-settings.png
โโโ 02-navigate-to-plugins.png
โโโ 03-final-result.png
- Index page Banner
- Step 111
Embedding Images in Markdownโ
Reference images relative to index.md:

Always write descriptive alt text โ it improves accessibility and SEO.
Tools like Snagit make it easy to produce annotated, professional-quality screenshots. See this article as a reference for the image quality standard we aim for.
Step 12: Update the Databaseโ
All blog data is linked in the database folder (\database\blogs\index.tsx). Update it with the following details:
{
id: sequence_wise,
title: "Title of the post",
image: "relative path of the cover image for the blog post",
description: "A short (2-3) lines of description of the post",
slug: "The name of the blog folder (keep it exact)",
authors: ["your-author-id"],
category: "The category the blog belongs to",
tags: ["tags or topics the blog is related to (tools or technologies)"],
}
All details are necessary for correctly rendering the blog card on the blogs page. Take a close look and make sure everything is filled in.
Admonitions: Tips, Notes, Info, and Cautionsโ
Use Docusaurus admonitions to highlight important information. Don't overuse them โ only where they add real value.
For tips and helpful extras:
:::tip[Need Git Commands?]
Check out our [comprehensive Git Commands Cheatsheet](/docs/GitHub/setup-environment/git-commands)
with 50 essential Git commands and examples.
:::
For extra context or caution:
:::info
In the picture below, Developer 1 handles the men's shopping section, Developer 2
deals with the women's section, and Developer 3 works on the login feature.
:::
For key feature callouts:
:::note
Key Features of GitLab:
- GitLab provides **built-in CI/CD pipelines**.
- Unlike GitHub, GitLab can be **self-hosted** or used on the cloud (GitLab.com).
- GitLab offers [Premium Plans](https://about.gitlab.com/pricing/) with advanced CI/CD and security features.
:::
Tables: Center Alignment via :::infoโ
Plain Markdown tables are left-aligned by default in Docusaurus. Wrap your table in an :::info block to center it:
:::
| Command | Description |
|-------------|-------------------|
| `git init` | Initialize a repo |
| `git clone` | Clone a repo |
:::
Rendered Outputโ
| Command | Description |
|---|---|
git init | Initialize a repo |
git clone | Clone a repo |
FAQ Section (Required)โ
Every blog post must end with a FAQ section before the conclusion. Use questions your readers are likely to have:
## Frequently Asked Questions
**Q: Do I need to know X before starting this guide?**
A: Basic familiarity with Y is helpful, but the guide covers everything step by step.
**Q: Will this work on Windows?**
A: Yes, the steps are cross-platform. Windows-specific commands are noted where they differ.
Before starting any development, make sure your blog meets all of the following criteria. Your blog can be rejected if any requirement is not fulfilled:
-
- 5 backlinks to different external websites to support our documentation.
-
- 5 internal backlinks to other articles on recodehive.
-
- No generic content โ avoid surface-level topics like "what is Azure" or "difference between X and Y". Write pure, high-depth technical articles with images. See this example for the standard we aim for. (Tip: tools like Snagit help produce great annotated screenshots.)
-
- Image filenames must be descriptive and SEO-friendly โ no random names like
screenshot123.png.
- Image filenames must be descriptive and SEO-friendly โ no random names like
-
- Content-to-code ratio: text should be more than code. Keep the ratio the other way round. If code is long, link to GitHub and reference it in comments instead.
-
- Include a bulleted summary section at the top of the blog post.
-
- Include a FAQ section at the bottom.
-
- Use Docusaurus admonitions (
:::tip,:::info,:::note) for callouts, tips, and cautions (see formatting guidelines below).
- Use Docusaurus admonitions (
-
- Tables must be center-aligned - wrap them in an
:::infoblock to achieve this in Docusaurus.
- Tables must be center-aligned - wrap them in an
-
- Use named code blocks with a filename label when showing code (e.g.,
```java title="Sample.java").
- Use named code blocks with a filename label when showing code (e.g.,
-
- When showing a query and its output together, use a Tabs block with separate "Query" and "Output" tabs.
-
- Screenshots must follow the naming convention and size guidelines below.
Step 10: Preview Your Postโ
Do lint check and then build before push
Make sure your dev server is still running (npm start), then navigate to http://localhost:3000/blog to see your post in the listing and click into it to read the full content. Verify:
- The frontmatter title, date, and author show correctly.
- The truncate preview looks right on the blog index.
- The bulleted summary section appears near the top.
- All images load and are properly sized.
- Code blocks are syntax-highlighted and have filename labels.
- Query/output pairs use Tabs.
- Tables are center-aligned inside
:::infoblocks. - Tips and notes use the correct admonition type.
- The FAQ section is present at the bottom.
Step 11: Commit and Push Your Changesโ
Once you are happy with the preview, stage and commit your files:
git add blog/your-blog-title/
git add blog/authors.yml # only if you added yourself
git commit -m "blog: add post on your-blog-title"
Push the branch to your fork:
git push origin blog/your-blog-title
Step 12: Open a Pull Requestโ
-
- Go to your fork on GitHub โ you will see a "Compare & pull request" banner. Click it.
-
- Set the base repository to
recodehive/recode-websiteand base branch tomain.
- Set the base repository to
-
- Write a clear PR title, e.g.
blog: Add post on Your Blog Title.
- Write a clear PR title, e.g.
-
- In the description, briefly summarize what the post covers.
-
- Click Create pull request.
A maintainer will review and merge your post. You may be asked to make small edits before it is approved.
Keeping Your Fork Up to Dateโ
Before starting a new post, pull the latest changes from upstream to avoid merge conflicts:
git checkout main
git fetch upstream
git merge upstream/main
git push origin main
Quick Reference Checklistโ
Before submitting your PR, go through this checklist:
-
- Blog folder created at
blog/your-blog-title/index.md
- Blog folder created at
-
- Frontmatter is complete (title, authors, tags, date, description, draft: false)
-
- Author entry exists in
blog/authors.yml
- Author entry exists in
-
-
<!-- truncate -->comment placed after the intro paragraph
-
-
- Bulleted summary section included near the top of the post
-
- FAQ section included at the bottom of the post
-
- No generic content โ article is high-depth and technical with images
-
- 5 external backlinks to supporting websites
-
- 5 internal backlinks to other recodehive articles
-
- Text is more than code โ long code blocks link to GitHub instead
-
- Code blocks use filename labels โ e.g., opening fence followed by
python title="app.py"
- Code blocks use filename labels โ e.g., opening fence followed by
-
- Query + output pairs use Tabs blocks
-
- Tables are wrapped in
:::infofor center alignment
- Tables are wrapped in
-
- Tips, notes, and cautions use the correct Docusaurus admonition
-
- All images are in
blog/your-blog-title/images/with SEO-friendly names
- All images are in
-
- Cover image is 1200 ร 630 px; step screenshots are no wider than 1280 px
-
- Image file sizes are under 500 KB each
-
- Post previews correctly at
localhost:3000/blog
- Post previews correctly at
-
- Database entry added in
\database\blogs\index.tsx
- Database entry added in
-
- Committed on a feature branch (not
main)
- Committed on a feature branch (not
-
- Pull request targets
recodehive/recode-websitemainbranch
- Pull request targets
Your vote helps us improve our docs.
All our docs are open source. Found a typo, want to add detail or have a better explanation? Anyone can contribute.














Comments
Powered by GitHub Discussions