This is the step-by-step guide for contributing a post to the Kubesimplify blog. Every post is a single Markdown file in this repo, so writing for us means opening a pull request, nothing more. You keep your byline, the canonical URL, and the SEO value, and we promote it across YouTube, X, LinkedIn, and Substack.
If you just want the short version, it lives on the site at blog.kubesimplify.com/write. The guide below is the long, do-it-yourself version.
A few facts that make the rest of this guide make sense:
- The site is a Next.js static site. There is no CMS and no database.
- Each post is one Markdown file in
content/blog/. The filename (minus.md) is the post's URL slug. - Authors live in
content/authors.json. Images live inpublic/img/. - On merge to
main, the site rebuilds and deploys automatically. Your post is live within minutes.
Note: the older
CONTRIBUTING.mdmentions Docusaurus and Yarn. That is out of date. The current stack is Next.js with npm, as described here.
- Node.js 18 or newer (
node -v) - npm (ships with Node) (
npm -v) - git and a GitHub account
- A text editor you are comfortable writing Markdown in
You do not strictly need to run the site locally to contribute, but previewing your post before you open the PR catches almost every formatting problem, so it is worth the five minutes.
-
Click Fork on github.com/kubesimplify/website.
-
Clone your fork:
git clone https://github.com/<your-github-username>/website.git cd website
-
Add the original repo as
upstreamso you can pull in updates later:git remote add upstream https://github.com/kubesimplify/website.git
-
Create a branch for your post (name it after your slug):
git checkout -b blog/my-post-slug
npm install
npm run devOpen http://localhost:3000/blog. The dev server hot-reloads, so as you edit your Markdown file the page updates instantly. Drafts (draft: true) are visible in dev but hidden in production, which is exactly what you want while writing.
Open content/authors.json and add an entry. The key is your handle (lowercase, kebab-case); you will reference it from your post's frontmatter.
"your-handle": {
"handle": "your-handle",
"name": "Your Name",
"avatar": "/img/authors/your-handle.jpg",
"bio": "One or two sentences about you. Shown on your author page and in schema.org metadata.",
"socials": {
"twitter": "https://x.com/you",
"linkedin": "https://www.linkedin.com/in/you/",
"github": "https://github.com/you",
"youtube": "https://www.youtube.com/@you",
"hashnode": "https://hashnode.com/@you"
}
}- Every field except
handleandnameis optional. Leavebioas""if you would rather not have one; it is then hidden. - Drop your avatar image in
public/img/authors/your-handle.jpg(or.png/.jpeg). Square images look best. If you skip it, a default Kubesimplify logo is used. socialskeys are free-form; the ones above are the common ones. Each becomes asameAslink in your structured data.
If you skip this step entirely, your post still publishes, but it falls back to the generic "Kubesimplify" byline. Add yourself; it is worth it.
Create content/blog/<your-slug>.md. Name the file exactly the same as your slug so the automatic "Edit this page on GitHub" link resolves correctly.
Start the file with frontmatter (the block between the --- lines), then write your post in Markdown below it:
---
title: "Your post title"
seoTitle: "SEO-optimized version of the title"
seoDescription: "1-2 sentence summary used as the meta description. Aim for under 160 characters."
datePublished: 2026-06-29T10:00:00.000Z
slug: your-slug
author: your-handle
cover: /img/blog/your-slug/cover.png
tags: ["kubernetes", "devops"]
---
Your post content starts here, in plain Markdown.| Field | Required | What it does |
|---|---|---|
datePublished |
Yes | ISO 8601 timestamp. A post with no datePublished will not appear at all. Posts are sorted newest-first by this value. |
title |
Yes | The post's <h1> and the default for seoTitle. |
slug |
Recommended | The URL path (blog.kubesimplify.com/<slug>). Defaults to the filename if omitted. Slugs are permanent; we never break them after publish, so choose one you will be happy with for years. |
author |
Recommended | Your handle from content/authors.json. Falls back to the generic Kubesimplify byline if omitted. |
seoTitle |
Optional | Title used in <title> and social cards. Defaults to title. |
seoDescription |
Optional | Meta description. If omitted, it is auto-generated from your first ~155 characters of prose. Writing your own is better. |
cover |
Optional | Path to your cover/OG image (/img/blog/<slug>/cover.png) or an absolute https:// URL. Used as the social-share image. |
tags |
Optional | Array of lowercase strings. Powers tag pages, related-post suggestions, and the article's topic metadata. Use 2 to 5. |
draft |
Optional | true keeps the post visible locally but hidden in production. Remove it (or set false) when you are ready to publish. |
Reading time is calculated automatically from your content; you do not set it.
Put every image for the post in its own folder:
public/img/blog/<your-slug>/
Reference them from the Markdown with an absolute path (the public/ prefix is dropped):
Your cover image goes in the same folder and is named in the cover frontmatter field. Keep images reasonably sized; large PNGs slow the page down. WebP, PNG, SVG, and JPG all work.
The body is standard Markdown with GitHub-Flavored Markdown extensions. What you get out of the box:
-
Headings are automatically given anchor links and feed the in-page table of contents. Start your sections at
##(the title is the#). -
Fenced code blocks with a language tag get syntax highlighting:
```bash kubectl get pods -A ```
-
Tables, task lists, strikethrough, and autolinks (GFM) all render.
-
Raw HTML is allowed if you need it, but reach for plain Markdown first.
A few tips that make posts shine:
- Show real commands and their real output. Practitioner detail is what readers come for.
- One topic per post. Two focused posts beat one sprawling 8,000-word essay.
- Link to other Kubesimplify posts where relevant (
/blog/<other-slug>).
Interactive React visuals (the
{{...-animation}}shortcodes you may see in some posts) are custom components maintainers build per-series. If you have an idea for one, raise it in your PR or an issue first.
With npm run dev running, open your post at http://localhost:3000/blog/<your-slug> and check:
- Code blocks render with the right language highlighting.
- Images load (broken images mean the path is wrong).
- The table of contents and headings look right.
- Your byline and avatar show up.
If your post is part of a multi-part series, open lib/series.js and add your slug to the relevant series' posts array in reading order, or create a new series entry following the comments at the top of that file. This adds a series banner and next/previous navigation. It is purely additive and never changes your post's URL.
We require a DCO sign-off on every commit (the -s flag adds it):
git add content/blog/your-slug.md content/authors.json public/img/blog/your-slug/
git commit -s -m "Add blog post: your post title"
git push -u origin blog/my-post-slugThen open a pull request from your fork against main. The PR template asks for a short description and screenshots; a screenshot of your post rendered locally helps reviewers a lot.
A preview deployment is built on every PR so reviewers (and you) can see the post live. We review for fit and clarity, never to gatekeep your voice. Once merged, it deploys automatically.
- Show, don't summarize. Real code, real commands, real output. Diagrams and screenshots where they help.
- Practitioner voice. What did you try? What broke? What do the docs not tell you? That is the gold.
- Stable, descriptive slugs. Pick one you will be happy with in five years.
- One topic per post.
- Original work or a fresh angle. Cross-posts from your own blog are welcome; just mention the original source in your PR.
---
title: ""
seoTitle: ""
seoDescription: ""
datePublished: 2026-06-29T10:00:00.000Z
slug:
author:
cover: /img/blog/SLUG/cover.png
tags: []
draft: true
---
Write here. Remove `draft: true` when you are ready to publish.- My post does not show up. It is almost always a missing or malformed
datePublished, ordraft: trueleft in (drafts are hidden in production). Check the frontmatter parses as valid YAML. - My images are broken. The path must start with
/img/...(nopublic/prefix) and the file must be committed. - The "Edit this page" link 404s. Your filename and
slugdo not match. Make them identical. - Author shows as "Kubesimplify". Your
authorhandle does not match a key incontent/authors.json.
Questions? Open an issue, or ask in the Kubesimplify Discord. Happy writing.