LinuxServer.io Blog

This repo is the blog at https://blog.linuxserver.io. Posts are Markdown files; merging to main publishes. You do not need to run anything locally to write a post.

(How the site itself is built and deployed is in DEVELOPMENT.md. You can ignore it.)

Writing a post in four steps

1. Make a folder

Create a folder under src/content/posts/. The folder name is the URL, so pick it carefully and keep it lower-case with hyphens:

src/content/posts/webtop-6-0-now-with-more-otters/     ->  https://blog.linuxserver.io/webtop-6-0-now-with-more-otters/

2. Put your images in the same folder

Everything the post needs lives next to it:

src/content/posts/webtop-6-0-now-with-more-otters/
├── index.md          <- the post
├── banner.jpg        <- hero image (top of the post, the card on the front page, social previews)
├── settings.png      <- any other images you reference from the text
└── diagram.svg

• Use plain file names: lower-case, no spaces (gpu-settings.png, not GPU Settings (final).png).
• Images are resized and converted to WebP at build time, so drop in the original. No need to shrink them first.
• JPG, PNG, GIF, WebP, AVIF and SVG all work.
• Videos are the one exception. Put .mp4/.webm files in public/media/<your-folder-name>/ (see step 4).
• The hero image is shown full-width behind the title, so landscape works best. Roughly 1600 x 900 or larger.

3. Write index.md

Start with the metadata block, then the article:

---
title: "Webtop 6.0: now with more otters"
date: 2026-10-22T09:00:00Z
author: TheLamer
tags:
  - webtop
  - docker
  - announcement
hero: ./banner.jpg
heroAlt: An otter sitting at a Linux desktop
description: Webtop 6.0 ships GPU acceleration on every desktop and drops X11 for good.
---

Your article starts here. Plain Markdown.

Field		What it does
title	required	Shown in the hero, on the card, in feeds and in the browser tab. Quote it if it contains a colon.
date	required	Publish date. Posts sort newest first. A date in the future keeps the post hidden until then. The T09:00:00Z time part can be anything; keep the Z.
author	optional	Your handle as you want it shown.
tags	optional	Free text. Each tag gets its own page at /tags/<tag>/. Reuse existing tags where one fits; the full list is at https://blog.linuxserver.io/tags/. Case does not matter.
hero	optional	Image in your folder, always written with the ./ prefix. Without it the post gets the stock circuit-board image.
heroAlt	optional	One sentence describing the hero image, for screen readers.
description	optional	One or two sentences for the front-page card, search engines and feeds. If you leave it out, the first paragraph is used, which is usually fine.
draft: true	optional	Keeps the post out of the published site while you work on it in a branch. Remove it when ready.
updated	optional	Set this when you materially revise a post later. Shown under the article as "Last updated".

Only title and date are required. Do not put the title as a # Heading at the top of the article; the hero already shows it.

4. Write the article

Standard Markdown, with these extras:

Images from your folder, relative path with ./:

![GPU settings dialog](./gpu-settings.png)

Code blocks are syntax highlighted. Name the language after the opening fence:

```yaml
services:
  webtop:
    image: lscr.io/linuxserver/webtop:latest
```

Common ones: bash, yaml, nginx, json, dockerfile, ini, python. Use text for plain output.

Callouts for notes and warnings:

> [!NOTE]
> Armhf images are no longer built.

> [!WARNING]
> This deletes your config folder. Back it up first.

Also [!TIP], [!IMPORTANT] and [!CAUTION].

Videos go in public/media/<your-folder-name>/ and are embedded with an HTML tag:

<video controls playsinline preload="metadata" src="/media/webtop-6-0-now-with-more-otters/demo.mp4"></video>

Links to other posts are just the slug with slashes: [the 5.0 post](/webtop-5-0-and-selkies-2-0-everything-everywhere-all-in-one-release/).

Tables and raw HTML work as-is. Headings get anchor links automatically, so [see setup](#setup) jumps to ## Setup.

Publishing

1. Branch, add your folder, open a PR. Reviewers can read the Markdown directly in the PR.
2. Merge to main. The site rebuilds and the post is live within a couple of minutes.
3. Edits later work the same way: change the file, merge.

The build fails the PR if the metadata is wrong (a missing title, an unquoted colon, a hero file that does not exist), so you will know before merge.

Previewing locally (optional)

If you want to see it before you push:

npm install
npm run dev

Then open http://localhost:4321. It reloads as you type. Drafts are visible here. Search is the only thing that does not work in this mode.

Checklist before you open the PR

• Folder name is the URL you want, lower-case with hyphens
• title and date set, hero points at a file that exists
• Image file names have no spaces
• No # Title heading at the top of the article
• Tags reuse existing ones where possible
• draft: true removed