About Docs

The documentation may not be fully up to date. Please refer to the disclaimer for important information about the project’s active development status, documentation accuracy, and ongoing efforts to stabilize the codebase.

This page serves as a style guide and reference for writing documentation for flwd. It outlines the conventions, formatting rules, and available components to ensure consistency across the documentation site.

Conventions

Tone: Professional, concise, and helpful.
Headings: Use sentence case. H1 is reserved for the page title. Use H2 (##) for main sections and H3 (###) for subsections.
Links: Use relative links with Hugo’s ref shortcode where possible: [link text]({{< ref "page.md" >}}) or [link text]({{< ref "page.md#anchor" >}}).

Callouts

We use Hextra’s callout shortcode to highlight important information. We have customized the styling to match the Catppuccin Frappé color scheme.

Syntax

{{% callout type="info" %}}
This is an **info** callout. Used for general information.
{{% /callout %}}

{{% callout type="warning" %}}
This is a **warning** callout. Used for important alerts.
{{% /callout %}}

{{% callout type="tip" %}}
This is a **tip** callout. Used for helpful hints or success messages.
{{% /callout %}}

{{% callout type="note" %}}
This is a **note** callout. Used for neutral notes or sidebars.
{{% /callout %}}

Rendering

Info Callout: This is the default type. Use it for general context, “did you know” facts, or neutral information that doesn’t require immediate action but is good to know.

Warning Callout: Use this for critical information, potential pitfalls, breaking changes, or things the user must pay attention to avoid errors.

Tip Callout: Use this for best practices, shortcuts, success states, or “pro tips” that help the user achieve their goal more efficiently.

Note Callout: Use this for side notes, technical details that are interesting but not critical to the main flow, or additional context.

Code Blocks

We use Chroma for syntax highlighting.

Standard Languages

Use standard language identifiers like yaml, json, bash, go, etc.

# Example YAML
apiVersion: v1
kind: Pod
metadata:
  name: flwd-pod

# Example Bash
flwd run job.yaml

HTTP / API Examples

We have custom styling for http code blocks to improve readability (light text on dark background).

Syntax:

```http
GET /api/v1/runs
```

Rendering:

GET /api/v1/runs

POST /api/v1/jobs
Content-Type: application/json

{
  "name": "example-job"
}

Inline Code & Tags

Inline code is styled with a subtle border and background to look like “tags”. This is useful for referencing configuration fields, file paths, or specific values.

Syntax: config.yaml, metadata.name, source

Rendering: The source field in flwd.yaml defines where jobs are loaded from.

Sources & Tree-v1 Structure