Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,19 @@ don't front-load complexity.
- Don't use "**Bold:** format" for subsection labels (use plain text
with colon)

### Guide structure

Guides are single-page - don't split a guide into multiple sub-pages
(for example, separate "overview", "configure", and "deploy" pages for
one guide). Cover the full task on one page and use headings to
organize sections.

Store each guide as a single Markdown file directly under
`content/guides/` (for example, `content/guides/django.md`), not
wrapped in its own directory with an `index.md`. Guide images belong in
the shared `content/guides/images/` folder, prefixed with the guide's
slug, not in a per-guide directory - see [Images](STYLE.md#images).

### Lists

- Limit bulleted lists to five items when possible
Expand Down Expand Up @@ -396,6 +409,13 @@ For code block syntax, language hints, variables, and advanced features
- Compress images before adding to repository
- Remove unused images from repository

**File organization:**

- Store guide images in the shared `content/guides/images/` folder,
not in a per-guide directory
- Prefix filenames with the guide's slug to avoid collisions (for
example, `kafka-architecture.webp`)

For image syntax and parameters (sizing, borders), see
[COMPONENTS.md](COMPONENTS.md#images).

Expand Down