← All notes

Guide: writing articles for sbayer.de

Published

Editorial

Also in: Deutsch, español

This page is for everyone who writes articles for sbayer.de.

The website is generated from plain text files in Markdown format. The closer a manuscript is to this format, the faster and more reliably it goes online. Word files or Google Docs are fine too, but then it matters even more to use only the formatting described here. Anything else is lost in the conversion.

The easiest way is to download the template and fill it in. It opens in any text editor.

What an article consists of

  1. The text as a single file, ideally Markdown (.md), otherwise Word or a link to a Google Doc.
  2. The front matter (see below), either at the top of the file or in the accompanying email.
  3. Images and downloads as separate files, not just pasted into a Word document.

Front matter

Every article needs a few details that are not part of the body text. In the template they sit between two lines of three hyphens:

---
title: "Keeping a Nextcloud folder in sync with rclone"
date: 2026-11-15
summary: "How to use rclone bisync to keep a folder in sync between a laptop and Nextcloud, and which pitfalls to watch out for."
tags: [NextCloud, Linux]
---
Field Meaning
title Headline of the article. About 70 characters at most, no full stop at the end.
date Intended publication date in the format YYYY-MM-DD.
summary One or two sentences, about 200 characters at most. Shown in the overview, in the RSS feed and in search engines. It should make sense on its own and not start with “In this article …”.
tags Two to four keywords. Reuse the keywords that already exist in the notes where possible.

We set the page address (e.g. sbayer.de/en/nextcloud-rclone-bisync/). If you have a preference, add it as permalink: nextcloud-rclone-bisync: lowercase letters, digits and hyphens only.

Structure of the text

No title in the text. The headline comes from the front matter. The text starts directly with the first paragraph.

Opening without a heading. One to three paragraphs saying what the article is about and who it is for. Someone who reads only this part should know whether it is worth reading on.

Subheadings on two levels:

## Section

### Subsection

Please do not go deeper than three hash signs. Subheadings are short and say something about the content (“Generating the key” rather than “Step 2”). For guides in several parts, the title reads “… – Part 1: …” and so on.

Short paragraphs. Three to six sentences. Leave a blank line between two paragraphs; a single line break is ignored.

Ending. A conclusion, a summary or further links are welcome but not required.

Formatting

The following is available and carried over exactly as written:

What How to write it
bold **important**
italic *term*
link [link text](https://example.com), always with the full address
bullet list lines starting with -
numbered list lines starting with 1. , 2. …
quote paragraph starting with >
code in the text `sudo apt update` (single backticks)
table like the tables on this page, simple content only

Code and commands spanning several lines go into a block of three backticks, followed by the language (bash, python, yaml, json …):

```bash
rclone bisync ~/Documents nextcloud:Documents --resync
```

Please write commands so they can be copied and run: without a leading $ and without output in the same block. Output goes into a separate block without a language.

Not carried over: fonts, font sizes and colours, underlining, centred text, multi-column layouts, text boxes, footnotes and automatic tables of contents. Emphasis is limited to bold and italic. Instead of a footnote, use a sentence in brackets or a link.

Images

  • Supply images as separate files (JPG for photos, PNG for screenshots), at least 1200 pixels wide, larger is fine. We resize them ourselves.
  • File names without spaces or special characters, e.g. rclone-conflict.png.
  • In the text, put a reference with a short image description in the right place:
![rclone conflict message in the terminal](rclone-conflict.png)
  • The description in square brackets is required. It is read aloud to people who cannot see the image and says what it shows.
  • A caption goes into its own italic paragraph directly below.
  • Only use images we have the rights to. For third-party images, please give the source and licence. Images are never embedded from other servers; they are stored on sbayer.de.
  • Check screenshots for personal data beforehand (names, email addresses, passwords, IP addresses).

Videos and embedded content

A YouTube link on its own in a separate paragraph automatically becomes a preview card with an image. The player only loads when someone clicks it. Until then, no connection to YouTube is made.

This video shows what it looks like in practice:

https://www.youtube.com/watch?v=VIDEO-ID

We do not carry over other embeds (social media posts, maps, forms, podcast players), because they send data to third parties as soon as the page loads. Just link to them normally instead.

Downloads

Scripts, configuration files or PDFs that belong to the article should be supplied as files and linked in the text:

The complete script is [available for download](backup-nextcloud.sh).

The text and the file must match. If the text shows a command or an excerpt, it should appear in the file exactly the same way.

Languages

The website appears in German, English and Spanish. It is enough to supply an article in one language; we create the other versions. If you translate yourself, keep the structure: the same sections, images and code blocks in the same order. Code is not translated, but comments in it are.

Revisions

When changing a published article, please send the complete new version and say in a sentence or two what has changed. The article then gets an “updated on …” note.

Checklist before submitting

  • title, date, summary and keywords provided
  • no title in the text, opening without a heading
  • subheadings only with ## and ###
  • links with the full address
  • code in blocks with a language, commands without $
  • all images as files, with a description, rights cleared, no personal data
  • downloads included and linked in the text
  • text, images and downloads sent to Stefan together, ideally as a ZIP