### Start VitePress Development Server

Source: https://github.com/ideamans/gridgram/blob/main/CLAUDE.md

Launches the VitePress development server for building and previewing documentation. This command first builds examples, logos, and LLM text files.

```bash
bun run docs:dev
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/ideamans/gridgram/blob/main/CLAUDE.md

Use this command to install project dependencies. Bun is the required runtime for this project.

```bash
bun install
```

--------------------------------

### Install gg with custom directory (Linux/macOS)

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/install.md

Installs gg to a specified directory, such as `$HOME/bin`, for per-user installation on Linux or macOS. Ensure the custom directory is added to your PATH.

```shell
curl -fsSL https://bin.ideamans.com/install/gg.sh | bash -s -- --install-dir "$HOME/bin"
```

--------------------------------

### Example starter gridgram diagram

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/skills/gg-author/SKILL.md

A basic example demonstrating how to define client, API, and DB nodes with icons and labels, and connect them with labels representing communication protocols.

```gg
icon :client @A1 tabler/world  "Client"
icon :api   @B1 tabler/server  "API"
icon :db    @B2 tabler/database "DB"

client --> api "HTTPS"
api    --> db  "SQL"
```

--------------------------------

### Verify Gridgram CLI Installation

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/index.md

Checks if the gg command is accessible and displays its help information. If not found, open a new shell or consult the installation guide.

```sh
gg --help
```

--------------------------------

### Document Settings Example

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

An example of a `doc` block within a .gg file, specifying document-level settings like cell size, padding, and layout.

```json
doc { cellSize: 256, padding: 10, columns: 5, rows: 10, theme: { primary: "#0000FF", secondary: "#FF0000", background: "#FFFFFF", fg: "#000000" }, icons: { "my-icon": "<svg>...</svg>" }, suppressErrors: true }
```

--------------------------------

### Example Icon References

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/skills/gg-icons/SKILL.md

These are examples of the literal reference strings that `gg icons` outputs, which can be directly used in `.gg` files.

```text
tabler/server       # for "API backend"
tabler/database     # for "storage"
tabler/cloud        # for "CDN" or "hosted service"
```

--------------------------------

### CLI Output Examples

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/cli.md

Shows various ways to use the `gg` CLI with different options to specify output files, formats, and dimensions.

```bash
gg diagram.gg -o out.svg
```

```bash
gg diagram.gg -o out.png --width 2048
```

```bash
gg diagram.gg --cell-size 128 -o out.png
```

```bash
gg diagram.gg --icons ./icons/ -o out.svg
```

```bash
gg diagram.gg --format json > merged.json
```

--------------------------------

### Install Sharp for PNG Rendering

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/integrations.md

Install the 'sharp' module to enable PNG rendering capabilities in your Node.js application.

```sh
npm install sharp
```

--------------------------------

### Install gridgram skills via GitHub CLI

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/plugin.md

Install individual gridgram skills using the `gh skill install` command. Specify the target agent using the `--agent` flag.

```bash
gh skill install ideamans/gridgram/plugins/gridgram/skills/gg-render --agent claude-code
gh skill install ideamans/gridgram/plugins/gridgram/skills/gg-icons
gh skill install ideamans/gridgram/plugins/gridgram/skills/gg-author
```

--------------------------------

### Install Gridgram CLI on Windows (PowerShell)

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/index.md

Installs the gg binary using PowerShell's Invoke-RestMethod and Invoke-Expression. Ensures the gg binary is added to your PATH.

```powershell
irm https://bin.ideamans.com/install/gg.ps1 | iex
```

--------------------------------

### Project Configuration Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/cli.md

Illustrates how to define project-wide settings using a `gridgram.config.ts` file, including cell size, theme, and asset aliases.

```typescript
// gridgram.config.ts
import { defineConfig } from 'gridgram'

export default defineConfig({
  cellSize: 200,
  theme: {
    primary: '#065f46',
    accent:  '#d97706',
  },
  assetAliases: {
    brand: './assets/brand',
  },
})
```

--------------------------------

### Grid Layout Diagram with Connectors

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

This example shows a 2x2 grid layout with nodes and connectors between them.

```gg
{{EXAMPLE_GRID}}
```

--------------------------------

### Project Configuration File Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/config.md

An example of a `gridgram.config.ts` file using `defineConfig` to set project-wide defaults for `cellSize`, `theme`, and `assetAliases`. This file is automatically discovered by Gridgram.

```typescript
// gridgram.config.ts
import { defineConfig } from 'gridgram'

export default defineConfig({
  cellSize: 128,
  theme: {
    primary: '#1e3a5f',
    accent: '#e8792f',
  },
  assetAliases: {
    brand: './assets/logos',   // → '@brand/aws.svg' resolves under here
  },
})
```

--------------------------------

### Install Gridgram CLI on macOS/Linux

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/index.md

Installs the gg binary using curl and bash. Ensures the gg binary is added to your PATH.

```sh
curl -fsSL https://bin.ideamans.com/install/gg.sh | bash
```

--------------------------------

### Fetching llms-full.txt with curl

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/discovery.md

This command-line example demonstrates how to fetch the complete Gridgram documentation and LLM reference bundle using curl and pipe it to an agent for context.

```bash
curl -s https://gridgram.ideamans.com/llms-full.txt | your-agent --context -
```

--------------------------------

### Install Gridgram

Source: https://github.com/ideamans/gridgram/blob/main/README.md

Install the gridgram package using npm or bun. Requires an ESM environment.

```bash
npm install gridgram
# or
bun add gridgram
```

--------------------------------

### Install Gridgram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/quickstart.md

Install the Gridgram TypeScript API using your preferred package manager.

```sh
npm install gridgram
# or
bun add gridgram
pnpm add gridgram
yarn add gridgram
```

--------------------------------

### CLI and TS-API Example Pair

Source: https://github.com/ideamans/gridgram/blob/main/CLAUDE.md

An example pair demonstrating identical rendering between the CLI form (diagram.gg) and the TS-API form (diagram.ts). These are used to ensure consistency in the documentation.

```typescript
// examples/example-name/diagram.ts
// This file should render identically to examples/example-name/diagram.gg
```

--------------------------------

### Install gridgram plugin from local checkout

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/plugin.md

For development, install the plugin directly from a local directory. Claude Code recognizes any directory with a `.claude-plugin/` as a plugin marketplace.

```text
/plugin marketplace add /path/to/gridgram/plugins/gridgram
```

--------------------------------

### Download and install gg from GitHub Releases (Linux/macOS)

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/install.md

Manually download, extract, and install a specific version of gg from GitHub Releases for Linux or macOS. Requires setting version, OS, and architecture variables.

```shell
VERSION=0.1.0
OS=linux       # or darwin
ARCH=amd64     # or arm64

curl -fsSL -o gg.tar.gz \
  "https://github.com/ideamans/gridgram/releases/download/v${VERSION}/gridgram_${VERSION}_${OS}_${ARCH}.tar.gz"

tar -xzf gg.tar.gz
sudo mv "gridgram_${VERSION}_${OS}_${ARCH}/gg" /usr/local/bin/
```

--------------------------------

### Verify Gridgram CLI Installation

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/workflow.md

Commands to verify that the Gridgram CLI tool is installed and accessible on the system PATH.

```sh
gg --help
gg icons --tags --limit 3
```

--------------------------------

### Install Gridgram Plugin

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/index.md

Use these commands to install the gridgram plugin for Claude Code. This allows Claude to use gridgram functionalities directly.

```bash
/plugin marketplace add ideamans/claude-plugins
/plugin install gridgram@ideamans-plugins
```

--------------------------------

### Testing Context7 Integration with MCP

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/discovery.md

These are example agent commands to test the integration with a running Context7 MCP server, verifying indexing and querying Gridgram's documentation.

```text
resolve-library-id("gridgram")
query-docs("how do I draw a region in gg")
```

--------------------------------

### Build Gridgram from source

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/install.md

Builds Gridgram from its source code using Bun. This involves cloning the repository, installing dependencies, syncing data, and compiling the binary.

```shell
git clone https://github.com/ideamans/gridgram
cd gridgram
bun install
bun run sync-tabler        # required after install (populates src/data/)
bun run compile            # produces ./gg in the repo root
```

--------------------------------

### Check Gridgram CLI Version

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/README.md

Verify the installation of the gridgram CLI by checking its version. This command should be run after installing the `gg` CLI.

```bash
gg --version
```

--------------------------------

### Saga: Distributed Transaction Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/microservices.md

Visualizes a three-step saga pattern for distributed transactions. The example supports stepping through different frames, showing the happy path, a failure scenario, and the compensating transaction.

```gg-diagram
<Example name="frame-gallery-saga" framing="1-3" layout="single" />
```

--------------------------------

### Icon Search Commands

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

Examples of using the `gg icons` CLI command to search for icons by tags, keywords, or format them as JSON.

```bash
gg icons --tags --limit 50
```

```bash
gg icons --tag <tag>
```

```bash
gg icons --search <query>
```

```bash
gg icons --search <query> --format json --limit 10
```

--------------------------------

### Primary with Read Replicas Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/database.md

Illustrates a database setup with a primary instance for writes and multiple read replicas for handling read traffic across different regions. Note the asynchronous lag for read replicas.

```gg-diagram
doc { cols: 4, rows: 2 }

region @B1:B2 "Write path" color=accent/30
region @C1:D2 "Read-only"  color=primary/28

icon :app @A1 tabler/server          "App"
icon :pri @B1 tabler/database        "Primary" sizeScale=1.4
icon :r1  @C1 tabler/database-export "r-1"
icon :r2  @D1 tabler/database-export "r-2"

app --> pri "writes" width=2
app --> r1  "reads"
app --> r2  "reads"
pri --> r1 dash="2 4"
pri --> r2 dash="2 4"

note @C2 (r1, r2) "Async\nlag ≤ 5s"
```

--------------------------------

### Minimal Gridgram Diagram

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

This example demonstrates the most basic Gridgram diagram with a single node.

```gg
{{EXAMPLE_MINIMAL}}
```

--------------------------------

### Feature Branch Preview Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/ci-cd.md

Shows a feature branch deployment with a dashed 'preview' path for peer review and a solid path for merge-to-main. Includes a note to guide reviewers.

```gg-diagram
doc { cols: 4, rows: 2 }

icon :pr      @A1 tabler/git-pull-request "PR"
icon :preview @B1 tabler/world             "Preview"
icon :merge   @C1 tabler/git-merge         "merge"
icon :main    @D1 tabler/server            "staging"

pr      --> preview "deploy" dash="2 4"
pr      --> merge
merge   --> main    "promote" width=2

note @B2 (preview) "URL posted\nback to the PR"
```

--------------------------------

### Verify gridgram installation in Claude Code

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/plugin.md

Run this command to test if the `/gg-icons` skill is available. If it's not found, use `/plugin list` to confirm the `gridgram` plugin is installed and enabled.

```text
/gg-icons
```

```text
/plugin list
```

--------------------------------

### Validate Plugin Skills

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/README.md

Run this command to validate the plugin skills before publishing. Ensure the `bun` package manager is installed.

```bash
bun scripts/validate-plugin-skills.ts
```

--------------------------------

### Download and install gg from GitHub Releases (Windows)

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/install.md

Manually download and extract a specific version of gg from GitHub Releases for Windows using PowerShell. The extracted gg.exe should be moved to a directory on your PATH.

```powershell
$Version = "0.1.0"
$Url = "https://github.com/ideamans/gridgram/releases/download/v$Version/gridgram_${Version}_windows_amd64.zip"

Invoke-WebRequest $Url -OutFile gg.zip
Expand-Archive gg.zip -DestinationPath .
# move gg.exe somewhere on your PATH, e.g. %USERPROFILE%\bin
```

--------------------------------

### Install Gridgram Plugin Locally in Claude Code

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/README.md

Use this command to add the local gridgram plugin directory as a single-plugin marketplace for testing within Claude Code.

```bash
/plugin marketplace add ./plugins/gridgram
```

--------------------------------

### CDN, Origin, and Cache Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/infrastructure.md

Visualizes a Content Delivery Network (CDN) setup with an origin server and a cache. It contrasts a cold cache (miss fans out to origin) with a warm cache (serves cached reply directly).

```gg-diagram
doc { cols: 4 }

region @A1:B1 "Cold Cache" color=accent/28
region @C1:D1 "Warm Cache" color=primary/28

icon :origin tabler/server "Origin"
icon :cache  tabler/cache "Cache"

origin --> cache "fill"
cache --> origin "miss"

note @A2 (cache) "Miss fills cache"
```

--------------------------------

### Active/Passive Multi-Region Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/infrastructure.md

Demonstrates an active/passive multi-region setup where traffic is routed to an active region via DNS. Failover is managed through health checks, and asynchronous replication is shown between databases in different regions.

```gg-diagram
doc { cols: 3, rows: 3 }

region @A1:C1 "DNS"    color=accent/24
region @A2:A3 "us-east (active)" color=primary/28
region @C2:C3 "eu-west (standby)" color=secondary/24

icon :dns  @B1 tabler/world       "DNS" sizeScale=1.2
icon :us   @A2 tabler/server      "us-east"
icon :eu   @C2 tabler/server      "eu-west"
icon :dbus @A3 tabler/database    "db-us"
icon :dbeu @C3 tabler/database    "db-eu"

dns  --> us    "100%" width=2
dns  --> eu    "0%"   dash="2 4"
us   <-> dbus
eu   <-> dbeu
dbus <-> dbeu  "async" dash="4 4"

note @B2 "Failover via\nhealth checks"
```

--------------------------------

### Color Grammar Examples

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/spec.md

Illustrates the various formats accepted for color definitions, including theme keywords, hex codes with and without alpha, CSS named colors, and CSS functions.

```plaintext
primary             # theme keyword (unmodified)
accent/60           # theme keyword + 2-digit hex alpha
accent/8            # single-digit alpha → expanded to 88
#e8792f             # hex literal
#e8792f40           # hex literal + alpha
red                 # CSS named color
rgb(200, 0, 0)      # any CSS function
```

--------------------------------

### Compute Render Dimensions Usage Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/render.md

Example of calling `computeRenderDimensions` to get the final rendered pixel size of the SVG, useful for pre-allocating containers or for image generation tools.

```typescript
const { width, height } = computeRenderDimensions(def, { renderWidth: 2048 })
```

--------------------------------

### Build Production Documentation

Source: https://github.com/ideamans/gridgram/blob/main/CLAUDE.md

Generates the production-ready documentation site using VitePress. Includes the same pre-build steps as the dev command.

```bash
bun run docs:build
```

--------------------------------

### Basic Connectors with Arrows and Labels

Source: https://context7.com/ideamans/gridgram/llms.txt

Define connectors between nodes with configurable arrow styles ('none', 'start', 'end', 'both'), dash patterns, and labels. This example shows default arrow at the end.

```typescript
import { tablerOutline, renderDiagramSvg, type DiagramDef } from 'gridgram'

const connectorExamples: DiagramDef = {
  columns: 2,
  nodes: [
    { id: 'a1', pos: [1, 1], src: tablerOutline('circle'), label: 'A' },
    { id: 'b1', pos: [2, 1], src: tablerOutline('circle'), label: 'B' },
    { id: 'a2', pos: [1, 2], src: tablerOutline('circle'), label: 'C' },
    { id: 'b2', pos: [2, 2], src: tablerOutline('circle'), label: 'D' },
    { id: 'a3', pos: [1, 3], src: tablerOutline('circle'), label: 'E' },
    { id: 'b3', pos: [2, 3], src: tablerOutline('circle'), label: 'F' },
  ],
  connectors: [
    // Arrow at end (default direction)
    { from: 'a1', to: 'b1', arrow: 'end', label: 'forward' },

    // Bidirectional arrow
    { from: 'a2', to: 'b2', arrow: 'both', label: 'sync' },

    // Dashed line with no arrow
    { from: 'a3', to: 'b3', arrow: 'none', dash: '6 3', label: 'optional' },
  ],
}
```

--------------------------------

### Basic CLI Usage

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/cli.md

Demonstrates the fundamental command structure for using the `gg` CLI to render a `.gg` file.

```bash
gg <input.gg> [options]
```

--------------------------------

### Global Settings with Doc Block

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/document/merging.md

Illustrates placing a `doc` block at the beginning of the file to define global settings like theme. `doc` blocks are processed in source order, allowing for logical grouping of configurations.

```gg
# --- global settings ---
doc { theme: { primary: '#065f46' } }
```

--------------------------------

### Render First Diagram on Windows (PowerShell)

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/index.md

Creates a PNG diagram from a one-line .gg source piped to the CLI. Reads from stdin using '-' and specifies output file and width.

```powershell
'icon :u tabler/user "User"; icon :a tabler/server "API"; u --> a "request"' | gg -o hello.png - --width 1024
```

--------------------------------

### Render First Diagram on macOS/Linux

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/index.md

Creates a PNG diagram from a one-line .gg source piped to the CLI. Reads from stdin using '-' and specifies output file and width.

```sh
echo 'icon :u tabler/user "User"; icon :a tabler/server "API"; u --> a "request"' | gg -o hello.png - --width 1024
```

--------------------------------

### Deep Merge of Theme Settings

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/document/merging.md

Demonstrates how theme settings are deep-merged. Later values for specific theme keys override earlier ones, while unset keys retain their previous values.

```gg
doc { theme: { primary: '#065f46' } }
doc { theme: { accent:  '#d97706' } }
```

--------------------------------

### Render Diagram Usage Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/render.md

Example of calling `renderDiagram` with options and handling potential diagnostics. Diagnostics indicate elements that couldn't be placed or routed cleanly.

```typescript
const { svg, diagnostics } = renderDiagram(def, { renderWidth: 1024 })

if (diagnostics.length > 0) {
  // One record per element that couldn't be placed or routed cleanly.
  // See the Diagnostics reference for the shape.
  console.warn(diagnostics.map((d) => d.message).join('\n'))
}
```

--------------------------------

### Streaming Pipeline with Consumers

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/data-pipelines.md

Demonstrates a Kafka-style event log fanning out to multiple consumers, with the log node emphasized using sizeScale and a distinct theme.

```gg-diagram
doc {
  cols: 3, rows: 3,
  theme: { primary: '#6d28d9', secondary: '#7c3aed', accent: '#db2777' },
}

icon :app   @A2 tabler/server         "App"
icon :kafka @B2 tabler/arrows-shuffle "Kafka" sizeScale=1.8
icon :sink  @C1 tabler/database       "DW"
icon :ml    @C2 tabler/brain          "ML"
icon :audit @C3 tabler/file-text      "Audit"

app   --> kafka width=2
kafka --> sink  dash="2 4"
kafka --> ml    dash="2 4"
kafka --> audit dash="2 4"
```

--------------------------------

### Onboarding Flow Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/customer-journey.md

Depicts a five-step onboarding process, emphasizing the dashboard as the final state. Uses compact steps arranged in a single row.

```gg-diagram
doc { cols: 5 }

region @A1:B1 "Account"       color=primary/24
region @C1:D1 "Setup"         color=secondary/24
region @E1:E1 "Ready"         color=accent/32

icon :signup  @A1 tabler/user-plus       "Sign up"
icon :verify  @B1 tabler/mail-check      "Verify"
icon :profile @C1 tabler/user-circle     "Profile"
icon :connect @D1 tabler/plug            "Connect"
icon :dash    @E1 tabler/layout-dashboard "Dashboard" sizeScale=1.4

signup  --> verify
verify  --> profile
profile --> connect
connect --> dash
```

--------------------------------

### Arrow Variants in Gridgram

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

This example showcases different arrow styles available in Gridgram for connectors.

```gg
{{EXAMPLE_ARROWS}}
```

--------------------------------

### Render .gg file to PNG

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/skills/gg-render/SKILL.md

Use this command to render a .gg file to a PNG output. Ensure the output file has the .png extension. This command respects user-supplied flags for width, scale, and frame. Requires the 'sharp' library for PNG generation.

```bash
gg <input.gg> -o <output>.png
```

--------------------------------

### Standalone and Multi-target Notes with Styling

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/note/index.md

Illustrates advanced note usage, including standalone notes for headers, multi-target notes pointing to multiple elements, and applying custom colors.

```gg
note @A1 "**Public** edge"   color=#0369a1
note @C1 "**Async** path"    color=#7c3aed
```

```gg
note @D3 (queue, store) "Both **read** after\nthe request completes"
```

```gg
note @B3 (req, api) "Rate-limited"  color=#b45309
```

--------------------------------

### Label Collision Diagnostic Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/workflow.md

JSON output indicating a label collision, showing the element ID and the positions that were attempted.

```json
[{
  "kind": "label-collision",
  "element": { "id": "api" },
  "attempts": ["right", "below", "above", "left"]
}]
```

--------------------------------

### Render Gridgram Diagram and Get Diagnostics

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/workflow.md

Commands to render a Gridgram diagram to SVG and capture validation diagnostics to separate files.

```sh
gg web-app.gg --format json --diagnostics --stdout > /tmp/envelope.json 2>/tmp/diag.json
gg web-app.gg -o web-app.svg
```

--------------------------------

### Auto-wrap Diagram with Doc Columns

Source: https://github.com/ideamans/gridgram/blob/main/src/templates/llm-reference.template.md

This example utilizes the 'doc { cols }' directive for automatic wrapping of nodes within a specified column count.

```gg
{{EXAMPLE_AUTO_WRAP}}
```

--------------------------------

### Run Full Unit Test Suite

Source: https://github.com/ideamans/gridgram/blob/main/CLAUDE.md

Executes all unit tests defined within the project.

```bash
bun test
```

--------------------------------

### Draft a .gg file with nodes and connectors

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/skills/gg-author/SKILL.md

Use this format to define nodes with IDs, icons, positions, and labels, and to establish connections between them with optional labels. Ensure IDs are unique and referenced correctly for connectors.

```gg
icon :id1 @A1 tabler/<name> "Label"
icon :id2 @B1 tabler/<name> "Label"

id1 --> id2 "edge label"
```

--------------------------------

### Generate Gridgram Diagram Source

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/workflow.md

Example Gridgram source code generated by Claude, defining icons, their labels, and relationships within a system.

```gg
icon :client @A1 tabler/browser  "Browser"
icon :api   @B1 tabler/api       "API"
icon :queue @C1 tabler/stack     "Jobs queue"

icon :db    @B2 tabler/database  "Postgres"
icon :cache @C2 tabler/bolt      "Redis"

client --> api   "HTTPS"
api    --> db    "SQL"
api    --> cache "get/set"
api    --> queue "enqueue"
```

--------------------------------

### Render SVG to PNG with Sharp

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/developer/integrations.md

Use the 'sharp' library to convert an SVG diagram generated by Gridgram into a PNG file. Ensure 'sharp' is installed.

```ts
import sharp from 'sharp'
import { renderDiagram, computeRenderDimensions } from 'gridgram'

const { svg } = renderDiagram(def, { renderWidth: 2048 })
const { width, height } = computeRenderDimensions(def, { renderWidth: 2048 })

await sharp(Buffer.from(svg))
  .resize(width, height)
  .png()
  .toFile('out.png')
```

--------------------------------

### Search Icons by Keyword

Source: https://github.com/ideamans/gridgram/blob/main/plugins/gridgram/skills/gg-icons/SKILL.md

Use this command when the user provides a general concept like 'database'. It searches for icons related to the keyword and returns a JSON list of the top matches.

```bash
gg icons --search database --limit 10 --format json
```

--------------------------------

### Matrix Build Diagram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/ci-cd.md

Illustrates a matrix build where a single commit fans out across multiple workers in parallel. Designed for clarity against richer examples.

```gg-diagram
doc { cols: 3, rows: 3 }

icon :src   @A2 tabler/git-commit  "Commit"
icon :n18   @B1 tabler/server      "18/linux"
icon :n20   @B2 tabler/server      "20/linux"
icon :n22   @B3 tabler/server      "22/linux"
icon :merge @C2 tabler/check       "Merge"   sizeScale=1.3

src --> n18
src --> n20
src --> n22
n18 --> merge
n20 --> merge
n22 --> merge
```

--------------------------------

### Classic ETL Pipeline

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/gallery/data-pipelines.md

Illustrates the simplest sequential ETL process with distinct source, extract, transform, load, and warehouse nodes.

```gg-diagram
doc { cols: 5 }

icon :src   @A1 tabler/database "Source"
icon :xtrct @B1 tabler/download "Extract"
icon :xform @C1 tabler/refresh  "Transform"
icon :load  @D1 tabler/upload   "Load"
icon :wh    @E1 tabler/database "Warehouse"

src --> xtrct
xtrct --> xform
xform --> load
load  --> wh
```

--------------------------------

### Define Icons and Connectors with IDs and Labels

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/first-gridgram.md

Use quoted strings for labels and the ':' prefix for node IDs when they are referenced by connectors or notes. Omit IDs for nodes that are not referenced.

```gg
icon :user tabler/user   "User"    # :user is the id; "User" is the label
icon :api  tabler/server "API"
user --> api "login"               # connector references the id
```

--------------------------------

### Icon Unresolved Diagnostic Example

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/ai/workflow.md

JSON output indicating an icon could not be resolved, specifying the element ID, the attempted icon source, and the reason.

```json
[{
  "kind": "icon-unresolved",
  "element": { "id": "db" },
  "iconSrc": "tabler/postgres",
  "iconReason": "not-found"
}]
```

--------------------------------

### Basic Note Syntax in Gridgram

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/note/index.md

Demonstrates the fundamental syntax for creating notes, including positioning, optional targets, and text content. Use for simple annotations.

```gg
note @B1 (api)     "Stateless\nauto-scaled"
note @A3 (login)   "Session token carried as Bearer JWT"
note @C3 (db, api) "Multi-target note" color=#b45309
note @D4           "Standalone — no leader line"
```

--------------------------------

### Gridgram CLI Emit LLM Documentation

Source: https://context7.com/ideamans/gridgram/llms.txt

Generates documentation for Large Language Models (LLM) in either Markdown or JSON format. Use the --format flag to specify the output format.

```bash
# Emit LLM reference documentation
gg llm                    # Markdown format
gg llm --format json      # JSON format
```

--------------------------------

### Connector Routing in Doc Block

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/connector/waypoints.md

Defines a routed connector with waypoints and other attributes within a `doc` block for better organization. This example uses fractional coordinates for waypoints.

```gg
doc {
  connectors: [
    {
      from: 'a', to: 'b', arrow: 'end',
      label: 'routed',
      waypoints: [
        { col: 2.5, row: 1 },
        { col: 2.5, row: 3 },
      ],
      nodeMargin: 0.8,
    },
  ],
}
```

--------------------------------

### Add Comments in .gg Files

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/document/index.md

Gridgram supports line comments using '#' or '//' for code clarity. This example shows a comment for a public layer icon definition.

```gg
# section: public layer
icon :web @A1 tabler/world "Web"   // externally visible
```

--------------------------------

### Define Single Cell or Range Region

Source: https://github.com/ideamans/gridgram/blob/main/docs/en/guide/region/spanning.md

Use '@c,r' for a single cell or '@c,r-c,r' for a range. Ranges are inclusive of both start and end cells.

```gg
region @C2 "one cell"
region @A1:D1 "Top row"
```