diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4a831568..335738eeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,10 @@ At Kubesimplify, we warmly welcome contributions through collaboration. We are excited to see that you want to contribute!. There are many ways in which one could contribute to Kubesimplify and every contribution is equally appreciated here. Navigate through the following to understand more about contributing here. +> **Want to write a blog post?** See the detailed, step-by-step guide in **[WRITING-A-BLOG.md](WRITING-A-BLOG.md)**. It covers authoring a post, frontmatter, images, previewing locally, and opening your PR. +> +> Note: the website now runs on **Next.js with npm** (blog posts are Markdown files in `content/blog/`). The Docusaurus and Yarn instructions in the sections below are outdated and apply to an earlier version of the site. + # Before you get started Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [our discord community](https://kubesimplify.com/discord) diff --git a/README.md b/README.md index 17c1cda72..ad086ba56 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ This repository contains the assets required to build the Kubesimplify website a

Contributing Guidelines:

We're a warm and welcoming community of open source contributors. Please join. All types of contributions are welcome. Be sure to read the Kubesimplify CONTRIBUTING.md for a tour of resources available to you and how to get started. + +📝 Want to write a blog post? Follow the detailed, step-by-step guide in WRITING-A-BLOG.md. This is the source code of the official [Kubesimplify's website](https://kubesimplify.github.io/website/). For new developers getting started, here are some instructions to follow: diff --git a/WRITING-A-BLOG.md b/WRITING-A-BLOG.md new file mode 100644 index 000000000..e3709c857 --- /dev/null +++ b/WRITING-A-BLOG.md @@ -0,0 +1,225 @@ +# Writing a blog post for Kubesimplify + +This is the step-by-step guide for contributing a post to the [Kubesimplify blog](https://blog.kubesimplify.com). 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](https://blog.kubesimplify.com/write). The guide below is the long, do-it-yourself version. + +## How the blog is built + +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/`](content/blog/). The filename (minus `.md`) is the post's URL slug. +- Authors live in [`content/authors.json`](content/authors.json). Images live in `public/img/`. +- On merge to `main`, the site rebuilds and deploys automatically. Your post is live within minutes. + +> Note: the older `CONTRIBUTING.md` mentions Docusaurus and Yarn. That is out of date. The current stack is Next.js with npm, as described here. + +## Prerequisites + +- **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. + +--- + +## Step 1: Fork and clone the repo + +1. Click **Fork** on [github.com/kubesimplify/website](https://github.com/kubesimplify/website). +2. Clone your fork: + + ```bash + git clone https://github.com//website.git + cd website + ``` + +3. Add the original repo as `upstream` so you can pull in updates later: + + ```bash + git remote add upstream https://github.com/kubesimplify/website.git + ``` + +4. Create a branch for your post (name it after your slug): + + ```bash + git checkout -b blog/my-post-slug + ``` + +## Step 2: Run the site locally + +```bash +npm install +npm run dev +``` + +Open [http://localhost:3000/blog](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. + +## Step 3: Add yourself as an author + +Open [`content/authors.json`](content/authors.json) and add an entry. The key is your **handle** (lowercase, kebab-case); you will reference it from your post's frontmatter. + +```json +"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 `handle` and `name` is optional. Leave `bio` as `""` 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. +- `socials` keys are free-form; the ones above are the common ones. Each becomes a `sameAs` link 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. + +## Step 4: Create your post file + +Create `content/blog/.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: + +```markdown +--- +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. +``` + +### Frontmatter field reference + +| 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 `

` and the default for `seoTitle`. | +| `slug` | Recommended | The URL path (`blog.kubesimplify.com/`). 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 `` 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. + +## Step 5: Add your images + +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): + +```markdown +![Architecture diagram](/img/blog/your-slug/architecture.png) +``` + +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. + +## Step 6: Write the body + +The body is standard Markdown with [GitHub-Flavored Markdown](https://github.github.com/gfm/) 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: + + ````markdown + ```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. + +## Step 7: Preview and proofread + +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. + +## Step 8 (optional): Add your post to a series + +If your post is part of a multi-part series, open [`lib/series.js`](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. + +## Step 9: Commit, push, and open a pull request + +We require a **DCO sign-off** on every commit (the `-s` flag adds it): + +```bash +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-slug +``` + +Then open a pull request from your fork against `main`. The [PR template](.github/pull_request_template.md) 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. + +--- + +## What we look for + +- **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. + +## Quick reference: copy-paste starter + +```markdown +--- +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. +``` + +## Troubleshooting + +- **My post does not show up.** It is almost always a missing or malformed `datePublished`, or `draft: true` left in (drafts are hidden in production). Check the frontmatter parses as valid YAML. +- **My images are broken.** The path must start with `/img/...` (no `public/` prefix) and the file must be committed. +- **The "Edit this page" link 404s.** Your filename and `slug` do not match. Make them identical. +- **Author shows as "Kubesimplify".** Your `author` handle does not match a key in `content/authors.json`. + +Questions? Open an issue, or ask in the [Kubesimplify Discord](https://kubesimplify.com/discord). Happy writing. diff --git a/app/blog/write/page.js b/app/blog/write/page.js index 9b27fb533..5ff2b2f2e 100644 --- a/app/blog/write/page.js +++ b/app/blog/write/page.js @@ -60,6 +60,18 @@ export default function WriteForUs() { <p className="text-lg max-w-2xl mx-auto" style={{ color: 'var(--text-secondary)' }}> Join {authorCount}+ contributors publishing in-depth, practitioner-led technical writing on Kubernetes, AI infrastructure, and cloud-native. </p> + <p className="text-sm mt-4" style={{ color: 'var(--text-secondary)' }}> + Prefer the full, do-it-yourself walkthrough?{' '} + <a + href={`${githubUrl}/blob/main/WRITING-A-BLOG.md`} + target="_blank" + rel="noopener noreferrer" + className="text-[var(--accent)] hover:underline font-semibold" + > + Read the detailed step-by-step guide + </a> + . + </p> </div> <section className="glass-card rounded-2xl p-6 md:p-8 mb-10"> @@ -193,10 +205,22 @@ export default function WriteForUs() { </p> <div className="flex flex-wrap gap-3 justify-center"> <a - href={`${githubUrl}/tree/main/content/blog`} + href={`${githubUrl}/blob/main/WRITING-A-BLOG.md`} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-2 rounded-full px-5 py-2.5 text-sm font-semibold text-white gradient-bg transition-transform hover:scale-105" + > + Step-by-step guide + <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"> + <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" /> + </svg> + </a> + <a + href={`${githubUrl}/tree/main/content/blog`} + target="_blank" + rel="noopener noreferrer" + className="inline-flex items-center gap-2 rounded-full border px-5 py-2.5 text-sm font-semibold transition-colors hover:bg-[var(--accent)]/10" + style={{ borderColor: 'var(--border-medium)', color: 'var(--text-primary)' }} > Browse existing posts <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">