Styleguide

Framework features🔗

Admonitions🔗

Basic Syntax

:::admonition[Title]{type=info collapsible open}
Collapsiple Info
:::

Types:

Info

Important information

Important

Important information

Tip

Important information

Example

Important information

Collapsible

Info

Collapsed info default open

Info

Collapsed info default closed

Custom title

Custom Title

Important information

Code Examples🔗

let
  is = nix: nix;
in
{
  this = is "valid";
}

Highlight Code in a Snippet

{
  this line is highlighted
  this line is NOT highlighted
  this line is highlighted
  this line is highlighted
  this line is highlighted
  this line is NOT highlighted
}

Writing Principles🔗

A consistent style greatly increases the usability of all documentation and communication. Please use this page as a reference and style guide for our internal and external documentation, blog posts, and all other Clan communication.

Knowledge Expectations🔗

What readers know:

• Basic computer operation
• Command line familiarity
• General interest in systems configuration

What readers don't know:

• Clan-specific concepts
• NixOS ecosystem details or grammar
• Deployment workflows

If specific knowledge is required, mention it at the start of the page.

Show, Don't Tell🔗

The fastest path to understanding is a working example. People learn by doing, not by reading about doing.

Recommended structure:

• Start with the minimal working code or command
• Briefly explain what it does
• Cover edge cases or variations
• Link to further information instead of including it

Grammar and Style🔗

Sentence structure:

• Use simple, direct sentences
• Break complex ideas into multiple short sentences
• Avoid nested clauses

Bad:

The following command, which utilizes nixos-facter to generate a comprehensive hardware report, will write the results back into the respective machine folder located on your setup device.

What the user does is hidden in the middle. nixos-facter is a leaked implementation detail. Users care about hardware scanning, not the tool that does it.

Good:

This command generates a hardware report and saves it to your machine folder.

Content Organization🔗

Lead with value. State what the reader will accomplish before explaining how.

Bad:

To create a new machine that you can later use as a webserver, first navigate to your Clan directory, then execute the clan machines create command with the --name flag followed by your desired machine name.

Good:

Create a new webserver machine in your Clan:

clan machines create - -name webserver

Use progressive disclosure. Introduce concepts only when needed.

Recommended structure:

1. State the goal (one sentence)
2. Show the simplest working example
3. Explain concepts if needed
4. Provide advanced options separately or link to the reference

Code Examples🔗

Keep examples focused:

• Show one concept at a time
• Use realistic but simple scenarios
• Avoid dependencies on other examples

Minimal comments

Let the code speak for itself. Paste code examples directly and without further alteration.

Bad:

# This sets the target host IP address for deployment
clan.networking.targetHost = "192.168.1.10"; # Change this to your machine's IP
# This enables SSH access
services.openssh.enable = true; # Required for Clan deployment

Good:

{
  clan.networking.targetHost = "192.168.XXX.XXX";
  services.openssh.enable = true;
}

Hide Nix Where Possible🔗

Nix knowledge is a barrier, not a feature.

• Prefer clan CLI commands
• Show configuration as what you want, not how Nix works
• Explain only what Nix does in the context of Clan

Bad:

Before adding a machine, you need to understand the NixOS module system and attribute set merging.

Good:

Add a machine:

clan machines create webserver

This creates machines/webserver/default.nix, where you can configure it via NixOS.

Teach Nix Through Examples, Not Theory🔗

(After respecting the prior point)

Users learn the NixOS module system by seeing patterns first.

• Start with a working example
• Explanation follows the code
• Link deeper concepts instead of inlining them
• Link to nix.dev for optional learning

General Rules🔗

• Abbreviate keys like ssh-ed25519 AAAAC3NzaC…
• Abbreviate IP addresses like 192.168.XXX.XXX
• Variables are capitalized and start with $, e.g. $YOUR-CLAN-NAME
• Variables should be directly usable during copy-paste
• Do not describe missing code parts (#elided, #omitted)
• Machines vs Devices:
  • machine = Clan identity
  • device = hardware

Capitalization🔗

• Clan
• GB / RAM / HDD
• bootable USB drive
• Wi-Fi / DHCP / DNS
• macOS / NixOS / Nix / Linux
• Flakes
• WireGuard
• ZeroTier
• git
• direnv
• Setup Device / Target Devices