Grid Notation

Grid Notation is a string of commands that GuideGuide reads from left to right. There are primary actions, add a guide and move the insertion point over to the right or down, depending on the orientation of the grid. So put in a sentence, grid notation tells GuideGuide, “Put a guide here, now move over, put a guide here, now move over, put a guide here, etc.”. There multiple types of commands that move the insertion point, each with different uses, and negative values can be used to move the insertion point backwards, allowing for things like guides outside of the selected context.

Thinking in Grid Notation

When beginning to think about grid notation, it may be helpful to think of something like the playhead in a video player. As the video progresses, the playhead moves from left to right. You can fast forward, rewind, and jump around.

Grid notation works similarly. When GuideGuide begins parsing grid notation, the hypothetical “playhead” starts at the left or top of the context, that is, at the coordinate 0 of the given axis. As grid notation’s commands are processed from left to right, each command manipulates where the “playhead” is located. Some commands provide literal movement instructions (10px or -1in), others provide instructions for how GuideGuide should move the “playhead” based on other calculated factors within the grid. Spread amongst the commands are | guides. When GuideGuide encounters these while parsing grid notation, it adds a guide at the current location of the “playhead”.

Reference

In the following guide, angle brackets <> are used to denote explanations within formatting examples. Angle brackets are not a part of grid notation syntax.

Grids

In grid notation, each line of text represents one axis along which guides can be placed. To produce a grid along more than one axis, each grid needs its own line of grid notation. For example, if you need to create columns and rows in a single grid notation block, you will have to create two grids, each on their own line.

For example, a grid with three columns and two rows:

# Three Columns
| ~ | ~ | ~ | (v)

# Two Rows
| ~ | ~ | (h)

Note that in GuideGuide plugins, text will automatically wrap if the grid you are writing is wider than the text box. This soft wrap is not a new line, and will not create a new grid. To indicate a new grid in your grid notation, you need a line break.

Whitespace

With a few exceptions, whitespace is optional within grid notation. Commands can be placed side-by-side without negative effects. However, such grids are generally hard to read, so GuideGuide will format any grid notation you enter to contain whitespace.

Commands

Commands are characters or groups of characters you use to write grid notation. GuideGuide processes each command in a grid notation string from left to right, following the action of the given command.

Guide commands

Format: |
In words: “Put a guide here”

The most important command to learn is the guide command. GuideGuide will place a guide when it comes across this command.

If you add more than one consecutive guide commands, GuideGuide will treat them as a single guide command to avoid duplicate guides. For example, these two grids will create the same result:

# When you type this
||| 10px |||
# This is how grid notation sees it
| 10px |

While including the guide command is important, omitting it can be useful too. For example, if you wanted a guide placed at the 2/3 point of a document, you could do so by creating a three column grid with wildcard commands, placing a guide between the second and third column, like so: ~ ~ | ~.

Explicit commands

Format: <number><unit>
In words: “Move over this much”

10px
1in
2cm

GuideGuide will move over the specified distance when it comes across an explicit command. Explicit commands support all unit types, and support multiples and fills.

Wildcard commands

Format: ~
In words: “Divide the leftover space between these evenly”

Wildcard commands are like explicit commands, in that they tell GuideGuide to move over a certain amount. Their size depends on how wide the grid is and the number of them that exist in the grid. This is the easiest way to create columns or rows based on the size of the context, to center something in the middle of your grid, or to push something to one side.

To determine the size of each wildcard, GuideGuide first subtracts the size of all explicit commands from the size of the grid or block, then divides the remaining space up between the wildcards. The result is that each wildcard command is the same size. If the grid options specify pixel calculation, GuideGuide distributes any pixels that remain after the division based on the remainder pixel distribution setting.

For example:

  • A guide on the left and right side of the context

    | ~ | (v)

  • A three column grid

    | ~ | ~ | ~ | (v)

  • A centered, 10px column

    ~ | 10px | ~ (v)

  • A guide on the right side of the context

    ~ | (v)

Wildcards cannot be used as fills. Doing so will cause an Unexpected Fill error. This is because wilcards do not have an intrinsic size, which would mean using them as a fill would create a division by infinity.

Variables

Variables enable you to define and reuse collections of commands within a grid. Variables need two parts: a declaration and a reference.

Declare

Format: $<ID> = <commands>
In words: “This variable equals these commands”

# Examples:
$ = | 10px |
$myGrid = | 1in | .25in |

When you declare a variable, you tell GuideGuide to remember a group of commands for later use. You write a variable with by the dollar sign $ followed by an optional string of letters and numbers.

Defining a variable does not add any guides, it just saves the commands for later use. To use the variable, you must reference it.

Variables are complete grids, and support all commands, as well as options.

Reference

Format: $<id>
In words: “Replace this variable with the commands it represents”

# Examples:
| $ |
| 10px | $A | 10px |

Referencing a variable tells GuideGuide to replace it with the commands that have been declared for that variable. You cannot reference a variable before it is declared. Doing so will cause an Undefined Variable error.

For example, a three column Grid using multiples of a variable command.

# This grid creates three columns.
$ = ~ |
| $*3 (v)
# Which expands to
| ~ | ~ | ~ | (v)

Variables may contain most commands, including wildcards. However, a variable that contains wildcard commands may not be used as a fill. Doing so will cause an error.

Built in variables

GuideGuide comes two built in variables, $WIDTH and $HEIGHT which can be used to reference the size of the context along the applicable axis. For example these are equivalent:

# A reference to the full width of the context
| $WIDTH | (v)
# Is the same as a single wildcard
| ~ | (v)

Multiples and Fills

You can add a duplication modifier to explicit, wildcard, and variable commands that will repeat the associated command a specified number of times. You can do this by suffixing the command with the asterisk symbol *. Depending on the number of duplications specified, the result will either be a multiple or a fills.

Multiples

Format: <command>*<number>
In words: “Repeat this command this many times”

# Examples:
$*4
10px*2
~*3

Multiples are commands followed by an asterisk *, followed by a number. When GuideGuide parses the command, it will repeat the command the given number of times. Because explicit and wildcard commands do not add guides, multiples are primarily useful in association with variables.

For example, to create three columns with margins:

$ = 10px | ~ | 10px |
| $*3 (v)

will expand to:

| 10px | ~ | 10px | 10px | ~ | 10px | 10px | ~ | 10px | (v)

Note that because grid notation treats duplicate guide commands as single guides, will ignore any duplication created by multiples.

Fills

Format: <command>*
In words: “Repeat this command until there is no space left”

# Examples:
10px*
$*

A fill is a command followed by an asterisk *. GuideGuide will repeat a fill command as until it fills the entire context. This is useful for creating baseline grids, or filling space with columns and gutters.

To calculate this, GuideGuide subtracts the size of all explicit commands from the size of the grid, then divides the remaining space by the size of the fill. The number of iterations is the absolute value of the result.

Wildcard take precedence over fills. As a result, if you use both wildcards and a fill in the same grid, only one instance of the fill will be created.

Grids cannot contain more than one fill.

Options

Format: (<modifiers> <grid size>)
In words: “Do the grid this way in this place”

# Examples:
( h 100px )
( 1in vl )
( hlp 1p5 )

Grid notation options let you specify two types of global options for each grid: modifiers, which affect how GuideGuide renders the grid, and an optional size, which constrains the size of the grid independent of the context. Place options between parentheses.

The order of options does not matter, but GuideGuide will format them so that modifiers are grouped together. If multiple or conflicting options of the same type are used, GuideGuide will accept the last option entered of each type.

Modifiers

Modifier options are represented by single characters.

Orientation

Use one of these values per grid:

  • h (default) horizontal
  • v vertical

Determines whether the guides are horizontal or vertical.

Calculation

Use one of these values per grid:

  • n (default) normal
  • p pixel snap

Determines whether GuideGuide rounds guide coordinates to whole numbers. If set to p, remainder pixel distribution will apply.

Remainder pixel distribution

Use one of these values per grid:

  • f first; left/top
  • c center
  • l (default) last; right/bottom

Determines to which wildcard commands GuideGuide will add remainder pixels. This is applicable when you set the calculation option to p.

For example, in a 10px space with 3 columns, a c value will create a grid that looks like:

| 3px | 4px | 3px |

Size

The grid size option may be an explicit command.

| ~ | ~ | (20px)

In the grid above, the wildcards will be calculated based on a size of 20px rather than the size of the context.

When a size is used, any commands that require calculation will be replaced with their calculated results in references thereafter. This can be used to manipulate how variables are interpreted.

$ = | ~ |
| $ |

The grid above is the equivalent of | ~ |, which means that when the variable is referenced, the wildcard will be calculated within the context. If the context was 100px, the wildcard would be 100px.

$ = | ~ | (10px)
| $ |

The example above is the same as the one before it, but a size as been specified. The wildcard is calculated within the variable declaration, so when the variable is referenced, it is the equivalent of | 10px |. If the context was 100px, the wildcard would be 10px.

This feature can be used to take calculated commands from one grid and use them as calculated in another grid, such as generating grids based on aspect ratios.

$ ~ ($WIDTH)
| $ | (v)
| $ | (h)

In the example above, a wildcard is calculated based on the width of the context. It is then referenced in a horizontal and vertical grid, creating a square of guides, regardless of the height of the context.

Variable references may also be used as size values. However, to do so, the referenced variable must also have a size specified when it is declared.

$ | ~ | (10px)
| ~ | ($)

Blocks

Format: { <commands> }
In words: “All of these commands are together”

Blocks allow the grouping of commands and change the options by which the enclosed commands are affected. A complete grid may be specified within the brackets of a block, including options.

For example, it is possible to use wildcards within a block to change the basis by which they are calculated. The following example creates a centered three columng grid.

~ | { ~ | ~ | ~ (100px)} | ~

The wildcards within the block are calculated based on the 100px size, while the wildcards outside the block are calculated based on the size of the context minus the size of the block.

Capturing Blocks

Format: $[<index>]
In words: “Get the commands of the block at the index provided”

When block appear within a variable, their commands can be referenced later. Index 0 represents all commands within the variable. Each index after that corresponds to a capturing block within the variable.

$ = | { 10px } |

In the the example above, $[0] would be | 10px | and $[1] would be 10px. This is handy, but it is more useful when combined with the fact that specifying a size option within a block will force its non-explicit commands to be calculated.

At the time the block commands are referenced, they have already been calculated within the context of the original variable. Thus, wildcards and fills retain the context of the variable in which they were specified.

$ = | { 10% } | ~ | 10% | (vnl $WIDTH)

# Reference it once for vertical guides
$ (v)

# Now do horizontal guides, referencing the margin from the vertical guides.
| $[1] | ~ | $[1] | (h)

The example above creates equally sized margins on all sizes of the context based on 10% of the width of the context.

Comments

Format: # <comment>
In words: “This is extra information that is ignored by grid notation”

As your grid notation gets more complex, you may want to leave notes to your future self. Lines that start with # will be ignored by grid notation.

# This comment doesn't get parsed, but the grid below it does.
| ~ |

Errors

As you type grid notation, GuideGuide displays errors it finds. These can be used to troubleshoot problems and understand mathematical limitations of some more complex uses of grid notation.

Unknown Command

This error occurs when you type something that grid notation does not recognise as a command.

Unexpected Fill

This error occurs when you place a fill * after a command that does not support it.

Undefined Variable

This error occurs when you reference a variable before you declare it.

Limitations

Grid notation tries to avoid telling you how to live your life. If you want to use percent commands that add up to more than 100%, that’s fine. If you want to specify a grid that is wider than the context, that’s fine too. Just keep in mind, what you are doing is beyond the logical bounds of the conventional grid math and may have unpredictable results.