Style Guide

Consistent style makes the site easier to read and easier to contribute to. This guide covers tone, formatting, and frontmatter conventions for playZE content.

Tone

• Direct and practical. Readers are trying to get better at ZE, not read an essay. Lead with what they need to do.
• Second person. “You hold here” not “Players hold here.”
• Present tense. “The door opens after 20 seconds” not “The door will open.”
• Skip filler phrases. Don’t start sentences with “It’s worth noting that” or “One thing to keep in mind is.”

Headings

Use ## (H2) for major sections and ### (H3) for subsections. Avoid skipping levels.

Heading text should be descriptive, not clever. “Stage 2 — Generator Room” is better than “The Gauntlet.”

Map stage headings

In map guides, ### (H3) is reserved for stages — each ### is auto-numbered with a stage badge. Sections within a stage must use #### (H4) or deeper, never ###. This keeps the automatic stage numbering correct.

Map guides must be authored as plain-Markdown .md files. The site automatically numbers and collapses ### Stage N — Name headings at build time. This behavior does not apply to .mdx files.

Map guide sections

Follow the template exactly — all eight sections, in order. Don’t add extra top-level sections or remove required ones. If a section genuinely doesn’t apply (e.g. no items on this map), write a brief sentence saying so rather than deleting the section.

Callout asides

Use Starlight’s :::note, :::tip, :::caution, and :::danger asides sparingly:

• :::note — supplemental information, things worth knowing but not critical.
• :::tip — a practical technique or optimization.
• :::caution — something players commonly do wrong.
• :::danger — a mistake that reliably wipes the round.

Don’t put every paragraph in a callout — use them for genuinely elevated information.

Tables

Use Markdown tables for item lists, command references, and comparison data. Keep columns narrow — don’t pad with empty cells.

Code blocks

Use fenced code blocks (triple backticks) for:

• Console commands
• Config file contents
• Binds

Always add a language tag where applicable:

• ```bash for shell commands
• No language tag needed for CS2 console commands (they don’t map to a standard language)

Links

Use relative Markdown links to other site pages:

• ✅ [Movement](/skills/movement/)
• ❌ [Movement](https://playze.gg/skills/movement/)

For external links, use the full URL.

Frontmatter fields

All pages

Field	Required	Notes
title	Yes	Sentence case. Keep under 60 characters.
description	Yes	One sentence. Used in search results and social previews. Under 160 characters.

Map pages (additional)

Field	Required	Notes
difficulty	Yes	One of: Easy, Medium, Hard, Insane
mapVersion	Yes	The version or Workshop ID the guide was written against
lastTested	Yes	ISO date: YYYY-MM-DD
stages	Recommended	Integer number of stages
tags	Optional	Array of strings

Freshness stamps

Every map guide must have a lastTested date and mapVersion in its frontmatter. Update these when you verify the guide against a newer map version — even if the strategies didn’t change. The date is a signal to readers about how current the guide is.

Images

Images are co-located with the map guide. Each map has a folder next to its markdown file named after the map (e.g. src/content/docs/maps/ze_best_korea/) holding that map’s screenshots. Reference them with a relative link:

• ✅ ![Cave entrance where humans start](./ze_best_korea/cave-entrance.webp)

Astro only bundles images that are actually referenced, so unused files never ship. (This is why images live under src/, not public/, which copies everything verbatim.)

Step layout: to pair an instruction with its screenshot side-by-side, write the instruction as a paragraph, then put the image(s) on the very next line:

Defend the cave entrance until both house doors open.

![Cave entrance](./ze_best_korea/cave-entrance.webp)

The site pairs them automatically at build time. Multiple images for one step go on consecutive lines and stack in the screenshot column. A paragraph with no image after it stays full-width prose.

Other rules:

• Keep filenames descriptive: stage2-hold.webp, not screenshot.webp.
• Add alt text to every image describing what it shows. Do not start alt text with “image of”, screen readers should already announce it as an image.
• Images should be converted to WebP’s using the script at ‘scripts/convert-image-to-webp.bat’ BEFORE committing to the repo.
• Videos should be converted to animated WebP’s using the script at ‘scripts/convert-to-720p-webp.bat’ BEFORE committing to the repo. Ensure you name your animated WebP’s ”…-Anim.webp’ or something similar so its easier to tell at a glance whats a video and what isnt.

What not to include

• Personal opinions framed as fact. “This map is bad” doesn’t help a player.
• Server-specific drama, names of specific players, or community conflicts.
• Strategies you haven’t personally verified. Mark unverified information with a :::note aside.
• Content from other guides without attribution