Guide: Creating and publishing blog posts

For DE/EN pairs, different slugs and tests, follow the maintenance guide in the repository .

Creating a new blog post

1. Create a new MDX file

German blog posts live at app/(de)/posts/<slug>/page.mdx, English posts at app/(en)/en/posts/<slug>/page.mdx. Static pages live in content/ and content/en/, respectively. To create a new post:

mkdir -p "app/(de)/posts/mein-neuer-beitrag"
touch "app/(de)/posts/mein-neuer-beitrag/page.mdx"

Naming conventions:

• Use descriptive lowercase filenames
• Use hyphens (-) instead of spaces
• Examples: erste-schritte.mdx, nextjs-tutorial.mdx, 2025-01-15-neuigkeiten.mdx

2. Basic structure of a post

Each blog post should start with frontmatter, followed by the content:

---
title: Mein erster Blogbeitrag
date: 2025-01-15
description: Eine kurze Beschreibung des Beitrags
tag: Tutorial
author: Ihr Name
---

Frontmatter configuration

Frontmatter contains metadata about your post. It appears at the very beginning of the file between lines of three hyphens (---).

Available fields:

Markdown syntax

Nextra supports full Markdown (MDX). Here are the main elements:

Headings

# H1 - Hauptüberschrift
## H2 - Unterüberschrift
### H3 - Unter-Unterüberschrift

Text formatting

**Fettgedruckt**
*Kursiv*
~~Durchgestrichen~~
`Code inline`

Lists

Unordered list:

- Punkt 1
- Punkt 2
  - Unterpunkt 2.1
  - Unterpunkt 2.2

Ordered list:

1. Erster Punkt
2. Zweiter Punkt
3. Dritter Punkt

Links

[Linktext](https://example.com)
[Interner Link](/andere-seite)

Code blocks

With syntax highlighting:

```javascript
function hello() {
  console.log("Hallo Welt!");
}
```

Supported languages: javascript, typescript, python, bash, css, html, json, yaml, etc.

Quotations

> Dies ist ein Zitat.
> Es kann über mehrere Zeilen gehen.

Tables

| Spalte 1 | Spalte 2 | Spalte 3 |
|----------|----------|----------|
| Zeile 1  | Daten    | Mehr     |
| Zeile 2  | Daten    | Mehr     |

Adding images and media

Images in the public folder

1. Create a public/images/ folder (if it does not exist):

   Copy codeWrap lines

   mkdir -p public/images

2. Copy your images into this folder

3. Include them in your post:

   Copy codeWrap lines

   ![Bildbeschreibung](/images/mein-bild.jpg)

Example with different image formats:

![Screenshot der Anwendung](/images/screenshot.png)
![Diagramm](/images/diagram.svg)
![Foto](/images/photo.jpg)

Images with captions:

![Eine schöne Landschaft](/images/landscape.jpg)
*Bildunterschrift: Die Berge im Sonnenuntergang*

Testing locally

Before publishing your post, test it locally:

1. Start the development server

cd nextra
npm run dev

The server will run at: http://localhost:3000 

2. Check the post

• Open your browser and navigate to http://localhost:3000
• Your new post should appear in the overview
• Click it to read it
• Check that:
  • ✅ Formatting is correct
  • ✅ Images are displayed
  • ✅ Links work
  • ✅ Code blocks are readable

3. Stop the server

# Drücken Sie Ctrl+C im Terminal
# Oder führen Sie aus:
pkill -f "next --turbopack"

Publishing

Create a production build

cd nextra
npm run build

This creates an optimised version of your blog in the .next/ folder.

Start the production server

npm run start

The production server runs on port 3000.

Deployment

Your blog runs at www.martuni.de . To publish changes:

1. Stop the running production server (if there is one)
2. Create a new build:
   Copy codeWrap lines

   npm run build

3. Restart the server:
   Copy codeWrap lines

   npm run start

Optional: Use a process manager such as pm2 for automatic restarts:

# PM2 installieren (falls nicht vorhanden)
npm install -g pm2
 
# Server mit PM2 starten
pm2 start npm --name "nextra-blog" -- start
 
# Server neustarten
pm2 restart nextra-blog
 
# Logs anzeigen
pm2 logs nextra-blog

Tips and best practices

✅ Do’s

• Use descriptive titles - They appear in search engines
• Always add a description - Important for SEO
• Test locally - Before publishing
• Use images - They make posts more interesting
• Structure your content - With headings and paragraphs
• Use code blocks - For technical content

❌ Don’ts

• Avoid oversized images - Optimise images before uploading (max. 1–2 MB)
• Avoid external dependencies - In MDX files
• Avoid spaces in filenames - Use hyphens
• Avoid invalid frontmatter - Check the YAML syntax

Further reading:

• Next.js documentation 
• Web Performance 

Common problems and solutions

Problem: The post does not appear

Solution:

• Check the frontmatter (valid YAML syntax?)
• Is the file in the appropriate App Router directory?
• Does the filename end in .mdx?
• Restart the server

Problem: Images are not displayed

Solution:

• Are the images in the public/ folder?
• Does the path start with /? (e.g. /images/bild.jpg)
• Is the filename spelled correctly?

Problem: Markdown does not render correctly

Solution:

• Check the syntax
• Insert blank lines between elements
• For code blocks: use three backticks

Support

For questions or problems:

• Check the Nextra documentation 
• See the Next.js documentation 

Happy blogging! ✍️