Version: 1.0 Last Updated: January 31, 2026 Applies To: All markdown documentation in /docs

This style guide ensures consistency across all 400+ documentation files in the nself project.

1. Brand & Terminology
2. Version References
3. Command Syntax
4. Placeholders
5. Code Blocks
6. Headers & Formatting
7. Links & References
8. Tables
9. Tone & Voice
10. File Organization

Use: nself (lowercase, no space)

Symbol: ɳSelf (Unicode ɳ + capital S)

• Use ɳSelf in:
  • Page titles
  • Hero sections
  • Marketing copy
  • Visual branding

DO NOT USE:

• ❌ NSelf
• ❌ Nself
• ❌ NSELF (except in environment variables)
• ❌ n-self
• ❌ n_self

Official tagline: "The complete self-hosted backend platform"

DO NOT USE:

• ❌ "Nhost Self-Hosted" (outdated)
• ❌ "Self-hosted Nhost" (outdated)
• ❌ Any reference to being "based on Nhost"

Correct positioning: nself is an independent platform, not a fork or derivative.

When comparing to other platforms:

Correct:

nself provides similar features to Supabase, Nhost, or Firebase, but runs entirely on your own infrastructure.

Incorrect:

nself is a self-hosted version of Nhost.
nself is based on Nhost's architecture.

Always use: The version from /src/VERSION

Current version: 0.9.8 (as of February 16, 2026)

• Use semantic versioning: vX.Y.Z
• Include v prefix in prose: "nself v0.9.9"
• Omit v in badges: version-0.9.9-blue

When a new version is released, update:

1. Badge references:

[![Version](https://img.shields.io/badge/version-0.9.9-blue.svg)](releases/v0.9.8.md)

2. Release notes links:

**[View v0.9.8 Release Notes](releases/v0.9.8.md)**

3. Version callouts:

> **v0.9.8 Note:** Commands consolidated. See migration guide.

Use this format for version-specific notes:

> **v0.9.8:** Brief note about change. 

Example:

> **v0.9.8:** Environment commands moved to `nself config env`. Old syntax still works.

All command examples must follow this format:

nself <command> <subcommand> [OPTIONS] [ARGUMENTS]

• Commands: lowercase
• Flags: lowercase with dashes
• Arguments: UPPERCASE or descriptive

Correct:

nself db migrate up
nself tenant create "Acme Corp" --slug acme --plan pro
nself deploy prod --dry-run

Incorrect:

Nself DB migrate up
nself Tenant Create "Acme Corp"
nself deploy PROD

Use descriptive lowercase or UPPERCASE for placeholders:

Preferred (descriptive):

nself tenant create <tenant-name>
nself db query <sql-query>
nself service logs <service-name>

Acceptable (UPPERCASE):

nself tenant create TENANT_NAME
nself db query SQL_QUERY

Choose ONE style per file - don't mix.

• Required arguments: <argument>
• Optional arguments: [argument]
• Optional flags: [--flag]

Example:

nself db migrate <direction> [steps] [--dry-run]

When documenting flags:

| Flag | Description |
|------|-------------|
| `--dry-run` | Show what would happen without executing |
| `--force` | Skip confirmation prompts |
| `--verbose` | Show detailed output |

Use: UPPERCASE_WITH_UNDERSCORES

PROJECT_NAME=myapp
POSTGRES_PASSWORD=secure123
MONITORING_ENABLED=true

Use: Descriptive paths with angle brackets

Edit `.env` and set:
```bash
CUSTOM_SERVICE_1=api:express-js:8001
```

Use: Consistent example names across all docs

DO NOT use:

• ❌ foo, bar, baz
• ❌ test123, asdf
• ❌ Real company names (except in real examples)

Always specify the language for syntax highlighting:

Correct:

```bash
nself start
```

```sql
SELECT * FROM users;
```

```typescript
const user: User = { id: 1, email: '[email protected]' };
```

Incorrect:

```
nself start
```

Use these identifiers:

• bash - Shell commands
• sql - SQL queries
• typescript - TypeScript code
• javascript - JavaScript code
• json - JSON data
• yaml - YAML configs
• dockerfile - Dockerfiles
• nginx - Nginx configs
• python - Python code
• go - Go code
• dbml - Database markup

Use comments to explain non-obvious parts:

# Start all services
nself start

# Wait for health checks (default 120s)
nself health check

Break long commands at logical points:

nself tenant create "Acme Corp" \
  --slug acme \
  --plan pro \
  --domain acme.example.com

# Page Title (H1) - ONE per file

## Major Section (H2)

### Subsection (H3)

#### Detail Section (H4)

Rules:

1. Only ONE H1 per file
2. Don't skip levels (H2 → H4)
3. Use sentence case, not Title Case
4. No punctuation at end

Correct:

# Database workflow guide

## Setting up migrations

### Creating your first migration

Incorrect:

# Database Workflow Guide.

### Setting Up Migrations (skipped H2)

• Bold for emphasis: **important**
• Italic for subtle emphasis: *note*
• Code for technical terms: `nself`

Correct:

The **database** must be running before you run `nself db migrate up`.

Unordered lists:

- Item one
- Item two
  - Nested item
- Item three

Ordered lists:

1. First step
2. Second step
3. Third step

Checklist:

- [ ] Not done
- [x] Completed

Use relative paths from current file:

[Quick Start](getting-started/Quick-Start.md)
[Database Commands](commands/DB.md)
[View Architecture](/architecture/ARCHITECTURE.md)

DO NOT use:

• ❌ Absolute paths: /do../getting-started/Quick-Start.md
• ❌ URLs: https://github.com/nself-org/cli/blob/main/docs/...

Use descriptive link text:

[Install Docker](https://docs.docker.com/get-docker/)
[PostgreSQL Documentation](https://postgresql.org/docs)

Avoid:

Click [here](https://example.com) to learn more.

When referencing commands:

See the `nself db migrate` command for details.

Link to command docs when first mentioned:

Use [nself db migrate](commands/DB.md#migrations) to run migrations.

Use aligned tables for readability:

| Command | Description |
|---------|-------------|
| `nself start` | Start all services |
| `nself stop` | Stop all services |

• Left-align text columns
• Right-align numeric columns
• Center-align status/icon columns

| Service | Port | Status |
|---------|-----:|:------:|
| PostgreSQL | 5432 | ✅ |
| Hasura | 8080 | ✅ |

For tables with code or long content, keep it simple:

| Variable | Example |
|----------|---------|
| `PROJECT_NAME` | `myapp` |
| `BASE_DOMAIN` | `local.nself.org` |

• Clear and concise - Avoid unnecessary words
• Active voice - "Run the command" not "The command should be run"
• Direct - Address reader as "you"
• Helpful - Anticipate questions and confusion

Good:

Run `nself start` to launch all services.

Bad:

The services can be started by executing the start command.

• Be precise with technical terms
• Don't oversimplify complex concepts
• Include warnings for dangerous operations

Example:

> **Warning**: `nself db reset` will **permanently delete** all data.
> This cannot be undone. Always backup first.

State prerequisites clearly:

## Prerequisites

Before starting, ensure you have:
- Docker Desktop installed
- At least 4GB RAM available
- Port 5432 not in use

• Use descriptive names: DATABASE-WORKFLOW.md not db.md
• Use UPPERCASE for major guides: README.md, Quick-Start.md
• Use kebab-case for multi-word: getting-started.md
• Use PascalCase for some titles: Quick-Start.md

Be consistent within a directory.

docs/
├── README.md                 # Main documentation index
├── getting-started/          # New user docs
├── guides/                   # Task-focused tutorials
├── commands/                 # CLI reference
├── configuration/            # Config guides
├── deployment/               # Production deployment
├── architecture/             # System design
├── services/                 # Service documentation
├── security/                 # Security audits & guides
└── releases/                 # Release notes & roadmap

Every directory should have an INDEX.md or README.md:

# Directory Name

Brief description of what's in this directory.

## Contents

- [File 1](/configuration/DATABASE.md) - Description
- [File 2](/commands/tenant/README.md) - Description

For migration guides and major docs:

---
title: Migrating from Firebase
difficulty: High
time_estimate: 16-32 hours
last_updated: 2026-01-31
---

For simpler docs, use a header:

# Guide Title

**Last Updated**: January 31, 2026
**Version**: 0.9.8
**Difficulty**: Medium

> **Warning**: This is a destructive operation.

> **Note**: Additional context or clarification.

> **v0.9.8**: Command syntax has changed. See migration guide.

> **Tip**: Use `--dry-run` to preview changes.

# Database Migrations

Manage your database schema changes with versioned migrations.

## Quick Start

Run all pending migrations:

```bash
nself db migrate up
```

Create a new migration:

```bash
nself db migrate create add_user_preferences
```

## Migration Files

Migrations are stored in `nself/migrations/`:

```
nself/migrations/
├── 001_create_users.sql
├── 002_add_preferences.sql
└── 003_create_orders.sql
```

> **Warning**: Running migrations in production requires extra caution.
> Always backup your database first.

## Next Steps

- [Seeding Data](/commands/db/README.md#seeding)
- [Backup & Restore](/guides/BACKUP-RECOVERY.md)

Before submitting new docs:

• Brand name is nself (lowercase) in code/commands
• Brand name is ɳSelf in titles where appropriate
• Version is current (0.9.8 as of Feb 2026)
• All code blocks have language identifiers
• Placeholders are consistent
• Commands use correct syntax
• Internal links use relative paths
• Headers follow hierarchy (H1 → H2 → H3)
• Tables are properly formatted
• Tone is clear and helpful
• No "Nhost Self-Hosted" references
• Examples use standard names (myapp, example.com)

This style guide should be:

1. Applied to all new documentation
2. Referenced in PR reviews
3. Used to refactor existing docs gradually
4. Updated as standards evolve