### Basic Anchor Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Demonstrates a simple anchor setup with orientation, shift, and rotation. This example shows how to set an initial orientation and then move and rotate the anchor point.

```yaml
anchor:
  orient: 45
  shift: [1, 0]
  rotate: 135
```

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

### Ergogen Configuration Examples

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Examples of Ergogen configurations for various scenarios like zone-level adjustments, post-adjustment zones, and asymmetry. These snippets showcase the YAML structure used in Ergogen.

```yaml

```

```yaml

```

```yaml

```

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

### Anchor Configuration Examples

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Demonstrates different anchor configurations in Ergogen, including default non-mirrored, default mirrored, and mirrored with resistance. These examples illustrate how the `resist: true` option affects the transformation of mirrored points.

```yaml
anchor_1:
  ref: left
  shift: [1, 0]
  rotate: 45

anchor_2:
  ref: left_mirror
  shift: [1, 0]
  rotate: 45

anchor_3:
  ref: left_mirror
  shift: [1, 0]
  rotate: 45
  resist: true
```

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

### Install Ergogen CLI

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/usage.md

Installs the latest Ergogen release globally using npm. Requires Node.js v14.4.0+ and npm v6.14.5+.

```shell
npm i -g ergogen
```

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

### Local Development Setup

Source: https://github.com/ergogen/ergogen-docs/blob/main/README.md

Commands to set up and run a local development server for Ergogen. It requires Node.js and Yarn. A workaround for OpenSSL 3.0 issues is also provided.

```bash
$ yarn
$ yarn start
```

```bash
NODE_OPTIONS="--openssl-legacy-provider" yarn start
```

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

### Parameterization Example

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/preprocessing.md

Shows how `$params` and `$args` enable regex-like replacements within declarations, allowing for pseudo-variables.

```yaml
top:
    value: placeholder
    double_value: placeholder * 2
    $params: [placeholder]
    $args: [3]
```

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

### Footprint Placement with Templating

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/pcbs.md

Example of placing footprints using templating to dynamically set parameters based on key-level attributes. This is useful for assigning nets to components.

```yaml
pcbs.<pcb_name>.footprints:
  - where: true # everywhere
    what: mx # Cherry MX type switches
    params:
      from: "{{from_net}}" # double curly braces means templating...
      to: "{{to_net}}" # so, reading from the point's key-level attributes
```

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

### Simple Ergogen Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Demonstrates a basic Ergogen configuration for defining points and zones in a matrix layout. This serves as a starting point for more complex configurations.

```yaml
points.zones.matrix:
```

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

### Skipping Example

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/preprocessing.md

Demonstrates the use of `$skip: true` to comment out declarations, useful for abstract or intermediary configurations, especially with inheritance and parameterization.

```yaml
grandparent:
    a: placeholder1
    b: placeholder2
    $params: [placeholder1, placeholder2]
parent:
    $extends: grandparent
    $args: [value1]
    $skip: true
child:
    $extends: parent
    $args: [,value2]
```

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

### Unnesting Example

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/preprocessing.md

Demonstrates how dot notation in keys is unnested into a nested object structure.

```yaml
nested.key.definition: value
```

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

### Ergogen Point Declaration Example

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Demonstrates how to declare a point with x, y, and rotation in Ergogen. Points are fundamental for defining keycap positions and orientations.

```python
point_declaration = [10, 20, 45]  # Represents x=10, y=20, r=45°
```

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

### Ergogen Layout Step 1: Anchor Determination

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Explains the first step in Ergogen's layout process: determining the zone's starting point based on the 'anchor' attribute. It highlights the initial mark's position and rotation, serving as the base for column generation.

```markdown
**Step 1**: We determine the starting point of the zone based on its `anchor` attribute.
In this case, only a 5° rotation was specified, so our initial mark is at `[0, 0, 5°]`.
This blue point is going to be our running "column anchor", where each column will start building from.
Since `spread` doesn't apply to the first column of any zone, and there's no `stagger` or `splay` given, we can start iterating over the zone's columns.
```

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

### Inheritance Example

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/preprocessing.md

Illustrates how the `$extends` key allows a declaration to inherit values from another, with rules for overriding and type precedence.

```yaml
top:
    parent:
        a: 1
        b: 2
child:
    $extends: top.parent
    c: 3
```

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

### Ergogen Anchor Declaration - Object

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Provides an example of an object-based anchor declaration, allowing for direct specification of transformations and references.

```javascript
object_anchor = { "from": "base_point", "dx": 10, "dy": 5, "dr": 15 }  # Anchor with transformations
```

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

### Ergogen Anchor Declaration - Array (Multi-Anchor)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Illustrates the use of an array for multi-anchor declarations, where each element is an anchor, and subsequent anchors use the previous one as their starting point.

```javascript
multi_anchor = [ "start_point", [5, 0, 0], { "dx": 10 } ]  # Chained anchors
```

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

### String Shorthands for Outline Operations

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Explains string shorthands for outline operations. A string starting with [+, -, ~, ^] followed by a name is equivalent to adding, subtracting, intersecting, or stacking an outline. Missing prefix defaults to addition.

```ergogen
~something: # equivalent to intersect operation
  what: outline
  where: undefined
  name: something
  operation: intersect
```

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

### Ergogen Anchor Attributes

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Defines the attributes used in Ergogen anchor declarations for specifying starting points, aggregation methods, orientation, shifting, rotation, affected fields, and resistance to mirroring.

```APIDOC
Attributes:

- ref: The starting point for anchor modifications. Can be a string name or a nested anchor.

- aggregate: Used when combining multiple locations as a starting point. Mutually exclusive with `ref`.
  - parts: Array of sub-anchors to aggregate.
  - method: Aggregation method (e.g., 'average'). Defaults to 'average'.
    - Note: Averaging applies to x/y coordinates and rotation (r).

- orient: Pre-rotation applied before shifting.
  - Can be a number (added to current rotation) or a sub-anchor (point turns towards the referenced point).
    - Note: Orienting only affects the `r` value.

- shift: Translates the point on the XY plane.
  - Can be an array of two numbers [x, y] or a single number parsed as [number, number].
    - Caution: Shifting happens according to the current rotation. Positive x shifts move right by default, but upward if rotated 90 degrees counter-clockwise.

- rotate: Post-rotation applied after shifting. Works the same as `orient`.

- affect: Overrides which fields (x, y, r) are affected during anchor calculation.
  - Can be a string (e.g., "xy") or an array of strings (e.g., ["x", "y"]).
    - Tip: Useful for copying specific properties like rotation from another point without affecting others.

- resist: Prevents special treatment for mirrored points. By default, shifts and rotations are mirrored for mirrored points to maintain symmetry. `resist` disables this behavior.
```

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

### Private Outlines Convention

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Explains the convention for 'private' outlines. Outlines whose names start with an underscore (e.g., '_my_name') are not exported and are intended for internal use as building blocks.

```ergogen
_my_name: # This outline is private
```

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

### Run Ergogen CLI (End User)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/usage.md

Executes Ergogen with a specified input configuration file and output directory. Use `ergogen --help` for all available options.

```shell
ergogen input.yaml -o output_folder
```

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

### Multi-Anchor Configuration (Follow-the-dots)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Illustrates setting up multiple anchors in sequence. The second anchor's position and orientation are influenced by the first, demonstrating a 'follow-the-dots' approach.

```yaml
anchor:
  - orient: 45
    shift: [1, 0]
    rotate: 135
  - shift: [1, 0]
    rotate.shift: [0, 0]
```

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

### Outline Parts Configuration (Array Notation)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Demonstrates the configuration of outline parts using array notation in YAML. This format is useful for listing parts sequentially.

```yaml
outlines:
  <outline_name>:
    - <part>
    - <part>
    - ...
  ...
```

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

### Ergogen Layout Step 2: Row Anchor Initialization

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Details the second step where the current column anchor is copied to a running 'row anchor' to begin laying out the first column. It notes the potential impact of key-level orientation, shifting, or rotation.

```markdown
**Step 2**: To start actually laying out the first ("pinky") column, we copy the current column anchor to a running "row anchor" (marked red).
Note that this is where key-level `orient`/`shift`/`rotate` would take effect, if any were specified.
```

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

### Zone and Global Adjustments Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Configuration structure for applying rotation and mirroring to keyboard zones, both individually and globally. Includes settings for zone-level rotation and mirroring, as well as global overrides.

```yaml
points:
  zones:
    zone_name:
      rotate: <number> # zone-level rotation
      mirror: <axis> # zone-level mirror
  rotate: <number> # global rotation
  mirror: <axis> # global mirror
```

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

### Outline Parts Configuration (Object Notation)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Illustrates the configuration of outline parts using object notation in YAML. This format can be beneficial for readability and when using YAML inheritance.

```yaml
outlines:
  <outline_name>:
    part1: <part>
    part2: <part>
    ...
  ...
```

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

### Run Ergogen CLI (Development)

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/usage.md

Executes a local copy of Ergogen from the source code. This is used for development and testing new features.

```javascript
node src/cli.js input.yaml -o output_folder
```

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

### Ergogen Layout Step 5: Iterating Through Rows

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Covers the fifth step, illustrating the process of continuing to add 'padding' and modifiers to generate subsequent row positions until all rows in a column are processed.

```markdown
**Step 5**: And we keep doing this until we run out of rows in the current column &ndash; cumulatively, always adding `padding` (and potential `orient`/`shift`/`rotate` modifiers) to get to the next location.
```

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

### Ergogen Metadata Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/metadata.md

Details the 'meta' section in Ergogen keyboard configuration files. It specifies the 'engine' for version compatibility, and 'version' and 'author' for KiCAD PCB metadata. Other arbitrary metadata can also be included.

```APIDOC
Metadata Configuration:
  meta:
    engine: <semver> (e.g., "3.1.4")
      - Specifies the minimum compatible Ergogen version.
      - Compatibility is checked as "at least X.Y.Z, up to (but not including) X+1.0.0".
      - Ergogen will error if the config's engine version is not compatible with the current Ergogen version.
    version: <string>
      - Metadata embedded in KiCAD PCBs as the version field.
    author: <string>
      - Metadata embedded in KiCAD PCBs as the author field.
    <any other key>: <any value>
      - Arbitrary metadata that Ergogen will ignore but can be useful for documentation or personal notes.
```

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

### Ergogen Configuration Structure

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/config-overview.md

The core structure of an Ergogen configuration file, outlining the required and optional keys.

```yaml
meta: <metadata> # optional
units: <units config...> # optional
points: <points config...> # required
outlines: <outline config...> #optional
cases: <case config...> #optional
pcbs: <pcb config...> #optional
```

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

### Clone Ergogen Repository

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/usage.md

Clones the Ergogen Git repository locally for development purposes.

```shell
git clone https://github.com/ergogen/ergogen.git
cd ergogen
npm install
```

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

### Custom Ergogen Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Illustrates a custom Ergogen configuration with user-defined key-value pairs within the matrix configuration. This allows for specific data to be associated with layout elements.

```yaml
points.zones.matrix.key:
  foo: bar
  answer: 42
```

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

### Autobind Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Illustrates the use of 'autobind' for automatic connection of points in Ergogen. This feature simplifies outline generation by calculating necessary extensions automatically.

```yaml
autobind: 10 # defer to autobind by default
```

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

### Ergogen PCB Configuration Block

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/pcbs.md

Defines the structure of a `pcbs` block in an Ergogen configuration file. This includes specifying outlines, footprints, reference visibility, PCB templates, and custom parameters.

```yaml
pcbs:
  <pcb_name>:
    outlines:
      - outline: <reference to existing outline> # required
        layer: <which KiCAD layer to draw on> # default = Edge.Cuts
      ...
    footprints:
      - where: <filter> # same as for outlines
        asym: source | clone | both # same as for outlines, default = both
        adjust: <anchor> # same as for outlines
        what: <footprint to use>
        params: <param object for the footprint>
      ...
    references: <boolean, whether to show component references on the pcb> # default = false
    template: <string> # name of the PCB template to use, default = kicad5
    params: <anything, pcb-level custom parameters passed to the template>
  ...
```

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

### Simple Ergogen Metadata

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Shows the internal representation of a simple Ergogen configuration, detailing the metadata generated for a matrix layout. This includes dimensions, spacing, and naming conventions.

```json
"matrix": {
  "x": 0,
  "y": 0,
  "r": 0,
  "meta": {
    "stagger": 0,
    "spread": 19,
    "splay": 0,
    "origin": [0, 0],
    "orient": 0,
    "shift": [0, 0],
    "rotate": 0,
    "adjust": {},
    "width": 18,
    "height": 18,
    "padding": 19,
    "autobind": 10,
    "skip": false,
    "asym": "both",
    "colrow": "default_default",
    "name": "matrix",
    "zone": {
      "name": "matrix"
    },
    "col": {
      "rows": {},
      "key": {},
      "name": "default"
    },
    "row": "default",
    "bind": [0, 0, 0, 0]
  }
}
```

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

### Ergogen Bundle Formats

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Bundles, used for custom footprints, are supported in ZIP archives or a custom EKB format.

```zip
/* Contents of a .zip bundle */
```

```ekb
/* Contents of a custom .ekb bundle */
```

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

### Ergogen Layout Step 3: Key Placement

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Describes the third step where a key is laid out at the finalized row anchor. It clarifies that the generated points represent the middle of keycaps, not the keycaps themselves.

```markdown
**Step 3**: When a row anchor is finalized, a key is laid out there &ndash; shown here by 18mm by 18mm squares, representing regular keycaps.
It's worth emphasizing that the keys we're generating here are always defined as the *middle points* of these visualization squares.
They're *not* the squares themselves, as we don't always necessarily want to put rectangles at these locations.
```

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

### Ergogen Matrix Zone Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

This YAML snippet defines the configuration for the 'matrix' zone in Ergogen. It includes settings for anchor rotation, column splay and stagger, and origin points, demonstrating how to structure a keyboard layout's matrix.

```yaml
points.zones.matrix:
  # we skew left a bit by default
  anchor.rotate: 5
  columns:
    pinky:
    ring.key:
      # inter-column splay resets subsequent columns to "upright"
      splay: -5
      stagger: 12
      # hinge at the bottom left corner of the key
      origin: [-u/2, -u/2]
    middle.key.stagger: 5
    index.key.stagger: -6
    inner.key.stagger: -2
  rows:
    bottom:
    home:
    top:
```

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

### Ergogen Layout Step 8: Repeating Column Process

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Describes the eighth step, where the process of generating columns is repeated. It involves establishing a new column anchor and laying out rows sequentially within that column.

```markdown
**Step 8**: From this new column anchor, we can repeat the same in-column process we saw before: copy it to a running row anchor, and create the column's relevant rows one by one, leaving `padding` in between stops.
```

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

### Ergogen Footprint API Reference

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/pcbs.md

Provides access to computed reference names, positioning values, and utility functions for managing nets within PCB footprints. Includes details on how to access and use these properties and functions.

```APIDOC
Footprint API:
  Properties:
    ref: Computed reference name of the component (e.g., "D4").
    ref_hide: Boolean flag to show/hide the reference on silkscreen.
    x: Numeric X-coordinate value.
    y: Numeric Y-coordinate value.
    r: Numeric rotation value (deprecated synonym for rot).
    rot: Numeric rotation value.
    xy: String representation of x and y, formatted as "${x} ${y}".
    at: Full KiCAD positioning clause, formatted as "(at ${x} ${y} ${r})".

  Functions:
    local_net(name: str) -> NetObject: Creates a net local to the footprint instance, prefixed with the footprint's reference (e.g., "D1_trace").

Footprint Coordinates:
  Coordinate Handling Functions:
    isxy(x: float, y: float) -> CoordinatePair:
      - Internal Symmetric positioning.
      - Inverts X if the source is mirrored.
      - Returns an object with 'x', 'y' (numeric) and 'str' (string formatted as "${x} ${y}").

    iaxy(x: float, y: float) -> CoordinatePair:
      - Internal Asymmetric positioning.
      - Ignores mirroring for X and Y shifts.
      - Returns an object with 'x', 'y' (numeric) and 'str' (string formatted as "${x} ${y}").
      - Note: Primarily for pattern completion; direct hardcoding within a module behaves similarly.

    esxy(x: float, y: float) -> CoordinatePair:
      - External Symmetric positioning.
      - Applies module transformation context (position, rotation) to external coordinates.
      - Negates horizontal shifts for mirrored points (Symmetry).
      - Returns an object with 'x', 'y' (numeric) and 'str' (string formatted as "${x} ${y}").

    eaxy(x: float, y: float) -> CoordinatePair:
      - External Asymmetric positioning.
      - Applies module transformation context to external coordinates.
      - Does not apply special mirroring treatment (Asymmetric).
      - Returns an object with 'x', 'y' (numeric) and 'str' (string formatted as "${x} ${y}").

  CoordinatePair Object:
    x: float - Calculated X-coordinate.
    y: float - Calculated Y-coordinate.
    str: str - String representation of coordinates, "${x} ${y}".
    __str__() -> str: Default string representation of the CoordinatePair object.
```

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

### Ergogen Layout Step 10: Negative Stagger Application

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Details the tenth step, showing the application of a negative 'stagger' value when generating columns, demonstrating how this affects vertical positioning.

```markdown
**Step 10**: Same old, same old, only now the `stagger` value is negative.
```

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

### Ergogen Layout Step 9: Iterative Column Generation

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Illustrates the ninth step, emphasizing the iterative nature of generating columns by repeating steps 6-8. This involves updating the column anchor and laying out subsequent columns row by row.

```markdown
**Step 9**: And now steps 6-7-8, again.
We create the new column anchor by `spread`ing/`stagger`ing/`splay`ing the old one, and lay out the next column, row by row.
```

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

### Explicit Bind Configuration

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Demonstrates the explicit 'bind' attribute for connecting points in Ergogen. This allows for precise control over how shapes extend to meet adjacent points.

```yaml
bind: num | [num_x, num_y] | [num_t, num_r, num_b, num_l]
```

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

### Ergogen Case Definition Structure

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/cases.md

This YAML structure defines how to configure cases in Ergogen. It specifies the 'what' (outline or case), 'name' (reference to an outline or case), 'extrude' dimension, spatial 'shift' and 'rotate' parameters, and the 'operation' for combining objects. It also notes that individual case parts can be arrays or objects for flexibility.

```yaml
cases:
    case_name:
        - what: outline # default option
          name: <outline ref>
          extrude: num # default = 1
          shift: [x, y, z] # default = [0, 0, 0]
          rotate: [ax, ay, az] # default = [0, 0, 0]
          operation: add | subtract | intersect # default = add
        - what: case
          name: <case_ref>
          # extrude makes no sense here...
          shift: # same as above
          rotate: # same as above
          operation: # same as above
        - ...
    ...
```

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

### Zone Definition Structure

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Provides the general structure for defining zones in Ergogen's `points` configuration. It outlines the hierarchy for naming zones, columns, and rows, and where to apply key-level attributes.

```yaml
points:
  zones:
    <zone_name>: # A unique key for each zone
      anchor: # Optional anchor to position the zone, default = [0, 0, 0°]
      columns:
        <column_name>: # A unique key for each column within the zone
          rows:
            <row_name>: <defs> # Key-level attributes set here apply to this key alone
            ...
          key: <defs> # Key-level attributes set here apply to the whole column
        ...
      rows:
        <row_name>: <defs> # Key-level attributes set here apply to the whole row
        ...
      key: <defs> # Key-level attributes set here apply to the whole zone
    ...
  key: <defs> # Key-level attributes set here apply to ALL zones
```

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

### Ergogen Layout Step 6: Moving to Next Column

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Details the sixth step, focusing on how Ergogen moves to the next column by applying 'spread' for horizontal movement and 'stagger' for vertical adjustment, while maintaining the column anchor's rotation.

```markdown
**Step 6**: Once the current column is done, we move on to the next column by applying `spread` (to move horizontally) and `stagger` (to move vertically).
Note that the column anchor is still "skewed" at the original 5° rotation.
```

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

### Ergogen String Filter Matching

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Explains how string filters work in Ergogen, including direct name comparison and the use of the 'tags' attribute for subset selection. It covers both array and object formats for tags.

```ergogen
string filter: compares against key name
tags attribute (array or object): used for subset selection
Example:
  filter: "matrix_pinky_home"
  filter: "/matrix_.*/" (regex)
  filter: "-alpha" (negation)
```

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

### Expand and Joints Syntactic Sugar

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Describes syntactic sugar for 'expand' and 'joints' fields. A single 'expand' value with a suffix ('), >, ]) translates to specific 'expand' and 'joints' values.

```ergogen
expand: 3] # equivalent to:
  expand: 3
  joints: beveled
```

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

### Ergogen Key Attributes

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Details the various key attributes used in Ergogen for defining keyboard layouts and key positioning. This includes parameters for staggering, spreading, splaying, padding, orientation, shifting, rotation, adjustments, binding, automatic binding, skipping, asymmetry, mirroring, naming, and dimensions.

```APIDOC
Key Attributes:

- stagger: Column staggering, a vertical shift to the starting point of a column. Default: 0.
- spread: Horizontal space between columns. Default: 'u'.
- splay: Rotation applied to the starting point of a new column. Default: 0.
- padding: Vertical gap between rows within a column. Default: 'u'.
- orient: Cumulative orientation within a column. Default: 0.
- shift: Cumulative shift within a column. Default: [0, 0].
- rotate: Cumulative rotation within a column. Default: 0.
- adjust: Independent adjustment for individual points, parsed as an anchor. Affects only the current key.
- bind: Directional reach for binding with neighbors. Can be a number, array of two numbers (horizontal/vertical), or array of four numbers (top, right, bottom, left). Default: -1 (no bind).
- autobind: Enables automatic binding. Default: 10.
- skip: Signals a helper point not to be included in the output. Default: false.
- asym: Determines the side of the keyboard the key belongs to. Default: 'both'.
- mirror: Overrides key-level attributes for mirrored keys. Default: empty.
- colrow: Built-in variable for a concatenated name of the column and row (e.g., '{{col.name}}_{{row}}').
- name: Unique key name globally (e.g., '{{zone.name}}_{{colrow}}').
- width: Keycap width for demo representation.
- height: Keycap height for demo representation.

Note: 'width' and 'height' apply only to the demo representation. For actual outlines, refer to the outlines section.
```

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

### Custom Ergogen Metadata

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Presents the metadata generated from a custom Ergogen configuration, including the added custom key-value pairs ('foo': 'bar', 'answer': 42) and their placement within the zone's key.

```json
"matrix": {
  "x": 0,
  "y": 0,
  "r": 0,
  "meta": {
    "stagger": 0,
    "spread": 19,
    "splay": 0,
    "origin": [0, 0],
    "orient": 0,
    "shift": [0, 0],
    "rotate": 0,
    "adjust": {},
    "width": 18,
    "height": 18,
    "padding": 19,
    "autobind": 10,
    "skip": false,
    "asym": "both",
    "colrow": "default_default",
    "name": "matrix",
    "foo": "bar",
    "answer": 42,
    "zone": {
      "key": {
        "foo": "bar",
        "answer": 42
      },
      "name": "matrix"
    },
    "col": {
      "rows": {},
      "key": {},
      "name": "default"
    },
    "row": "default",
    "bind": [0, 0, 0, 0]
  }
}
```

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

### Ergogen Layout Step 11: Zone Completion

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Describes the eleventh and final step for the 'matrix' zone, indicating the completion of the layout process after processing all columns, including the inner ones.

```markdown
**Step 11**: Once more for the inner column, and we're done with this zone.
```

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

### Ergogen Output Points Formats

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Ergogen can output points in several formats: raw input data, canonical YAML representation, or data suitable for demo visualization.

```raw
/* Raw point data */
```

```yaml
points:
  - x: 10
    y: 20
  - x: 30
    y: 40
```

```visualization
/* Data format for visualization */
```

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

### Ergogen Inheritance Order

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Details the precedence order for defining key-level attributes in Ergogen, from built-in defaults to key-specific overrides. This order ensures that more specific configurations take precedence over more general ones.

```APIDOC
Ergogen Inheritance Order:

1. Built-in, hardcoded defaults
2. Global `points.key` overrides
3. Zone-wide `points.zones.<zone_name>.key` overrides
4. Column-wide `points.zones.<zone_name>.columns.<column_name>.key` overrides
5. Row-wide `points.zones.<zone_name>.rows.<row_name>` overrides
6. Key-specific `points.zones.<zone_name>.columns.<column_name>.rows.<row_name>` overrides
```

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

### Custom Unit Definitions

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/units.md

Demonstrates how to define custom units or modify predefined ones using mathematical expressions. This allows for flexible and relative measurements in keyboard layouts.

```yaml
units:
  a: cy - 7
  b: a * 1.5
```

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

### Anchor Averaging

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Shows how to aggregate multiple anchor points. When no specific method is provided, it defaults to averaging the coordinates and rotations of the specified anchor parts.

```yaml
anchor:
  aggregate.parts:
    - left
    - right
  shift: [1, 0]
  rotate: 180
```

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

### Ergogen Layout Step 4: Padding for Next Row

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Explains the fourth step, where 'padding' is used to determine the position of the next row within the current column.

```markdown
**Step 4**: Now that the first key of the column is fixed, we add `padding` to figure out where the next row should go.
```

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

### Ergogen Advanced Filter Syntax

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Details the full form of Ergogen filters, which specify which key-level attributes to check, how to check them (similarity operator '~'), and the value to check against. It also explains how to combine filters using arrays for logical AND/OR operations.

```ergogen
Full form: meta.<attribute> ~ <value>
Example: meta.name ~ "something"
Combining filters:
  [filter1, filter2] -> OR
  [[filter1, filter2]] -> AND
```

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

### Custom Footprint Structure

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/pcbs.md

Defines the structure for a custom Ergogen footprint. It includes a `params` object for configurable properties and a `body` function to generate the KiCAD module string.

```js
module.exports = {
  params: {
    designator: '_', // the only semi-required param, for naming components on the PCB
    // and now any other param names, with default values supplied
    // note that the default value also tells Ergogen the param's type
    bool_param: true,
    string_param: 'default',
    number_param: 42,
    array_param: ['a', 'b', 'c'], // regular array
    object_param: {a: 1, b: 2, c: 3}, // regular object
    // expanded definitions, so we know these are not just regular objects
    net_param: {type: 'net', value: 'GND'},
    anchor_param: {type: 'anchor', value: 'existing_point_name'}
  },
  body: parsed_params => {
    // any procedural code returning "filled out" KiCAD footprint
    return `
      (module something (layer something)
        ${parsed_params.at}
        // bla bla bla
        ${parsed_params.any_other_param}
        // bla bla bla
      )
    `
  }
}
```

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

### Ergogen Layout Step 7: Applying Inter-Column Splay

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Explains the seventh step, which involves applying 'splay' for inter-column adjustments. It clarifies how 'splay' affects rotation and how the 'origin' parameter can modify the rotation point, potentially resetting rotation to upright.

```markdown
**Step 7**: After `spread`ing and `stagger`ing, inter-column `splay` is applied &ndash; again, cumulatively.
By default, `splay`ing happens "around" the point itself, so it doesn't affect its x/y position, only its rotation.
But we can change this with an optional `origin` to rotate around.
In this case, it's used so that the column hinges around the first key's bottom left corner (so that the rotation doesn't accidentally make that exact corner overlap the first column, as it would during sufficient rotation around the key's center).
Note that this `splay` takes us back to 0° (upright) rotation.
```

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

### Ergogen Input Configuration Formats

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Ergogen accepts configuration in JSON or YAML formats. It can also process JavaScript code that generates a configuration object, or any language that can produce JSON/YAML, especially when procedural features are required.

```json
{
  "key": "value"
}
```

```yaml
key: value
```

```javascript
module.exports = {
  key: "value"
};
```

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

### Ergogen Anchor Declaration - String Reference

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Shows how to use a string as an anchor, referencing an existing point by its name without modifications.

```javascript
anchor_string = "start_point"  # References a point named 'start_point'
```

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

### Custom Ergogen PCB Template Structure

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/pcbs.md

Defines the structure for a custom Ergogen PCB template using JavaScript. This includes functions to convert MakerJS shapes to KiCAD formats and to assemble the final PCB file.

```javascript
module.exports = {
  // convert MakerJS shapes into KiCAD shapes
  convert_outline: (model, layer) => {
    // ...
  },
  // create the final KiCAD PCB from the precomputed parts
  body: parts => {
    // ...
  }
}
```

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

### Predefined Ergogen Units

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/units.md

Defines the four standard units (`U`, `u`, `cx`, `cy`) used for key spacing in Ergogen. These represent common switch spacing measurements.

```yaml
U: 19.05 # 19.05mm MX spacing
u: 19 # 19mm MX spacing
cx: 18 # 18mm Choc X spacing
cy: 17 # 17mm Choc Y spacing
```

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

### Internal Variables for Defaults

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/units.md

Shows the use of internal variables that provide default values for key-level attributes like stagger, spread, splay, height, width, padding, and autobind. These can be overridden in the configuration.

```yaml
$default_stagger: 0,
$default_spread: 'u',
$default_splay: 0,
$default_height: 'u-1',
$default_width: 'u-1',
$default_padding: 'u',
$default_autobind: 10
```

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

### Ergogen Filter Data Types

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Demonstrates how Ergogen interprets filters based on their data types. Undefined filters produce a default origin, booleans control inclusion/exclusion, strings perform simple matching, objects/arrays with objects are treated as anchors, and arrays without objects are for complex filters.

```ergogen
undefined: default [0, 0, 0°] origin
boolean: true (all points), false (no points)
string: simple filter (name/tag matching)
object or array with object: anchor
array without objects: complex filter
```

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

### Ergogen Inheritance Suffix Distinction

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Highlights the difference in `.key` suffix usage between different inheritance levels in Ergogen. Levels 2-4 use the suffix because their parent levels can contain non-key attributes, while levels 5-6 omit it as they are exclusively for key-level attributes.

```APIDOC
Suffix Distinction:

- Levels 2-4: Use `.key` suffix (e.g., `points.zones.<zone_name>.key`)
- Levels 5-6: Do NOT use `.key` suffix (e.g., `points.zones.<zone_name>.rows.<row_name>`)
```

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

### Affecting Existing Anchor Properties

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/points.md

Demonstrates how to reference an existing anchor and selectively modify its properties using 'affect'. This allows for building upon previous configurations without overwriting them entirely.

```yaml
anchor:
  - shift: [0, 1]
  - ref: existing
    rotate: 180
    affect: r
```

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

### Ergogen Output PCB Format

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Ergogen can output PCBs in the KiCad PCB file format, supporting unrouted boards.

```kicad_pcb
(kicad_pcb (version 20211123) (host "Ergogen")
  (version 20211123)
  (host "Ergogen")
  (uuid "...")
  (layer F.Cu)
  (layer B.Cu)
  ;; ... other PCB elements
)
```

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

### Ergogen Output Outline Formats

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Outlines generated by Ergogen can be exported in DXF or SVG formats.

```dxf
/* DXF file content */
```

```svg
/* SVG file content */
```

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

### Ergogen Common Part Attributes

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Details the common attributes for defining parts in Ergogen, including shape declaration, placement filters, combination operations, mirroring, positioning adjustments, scaling, outline expansion, joint treatment, and corner filleting.

```APIDOC
what: declares *what* shape we want to place – see [Shapes](#shapes).

where: declares *where* we want to place those shapes – this is where we can use the previously discussed filters.

operation: indicates how we want the current part to combine with the cumulative result of previous parts.
  Options include:
    - add: produces an union – this is the default operation.
    - subtract: subtracts this part from the in-progress result.
    - intersect: computes the intersection of this part and the in-progress result.
    - stack: just draws the current part "on top of" the in-progress result (possibly crossing lines instead of calculating unions).
      ::tip
      `stack` can be used as a computationally "cheaper" `subtract` in some cases, but it's mostly for being able to visualize individual parts in the context of other parts and getting a sense of what happens (i.e., debugging).
      ::

bound: boolean value, representing whether we want to activate binding on the shapes or not.
  If `false`, the shapes are placed as-is.
  If `true`, the corresponding binding rectangles are added to each relevant side of each shape and the results union'ed.

asym: the field is a companion to the `where` filter and represents how filtering should treat mirrored points.
  The same values are available that we've discussed in the [Mirroring](./points.md#mirroring) section – the canonical choices are `source`/`clone`/`both`.

  - The default `source` only returns the points matched by the filter.
  - `clone` returns only the mirrored versions of the points that would be matched by the filter.
  - `both` returns both the regular matches and their mirror images.
    ::caution
    If the filter translates to an anchor, this check is ***strict*** – meaning that Ergogen will error out if the mirror image doesn't exist.
    On the other hand, the mirror check is permissive for regular filters, including them if they exist and ignoring the cases where they don't.
    ::

adjust: a relative anchor by which to adjust the position of each shape – similarly to the key-level `adjust` attribute.
  ::tip
  This field makes it possible to place shapes not only **at** certain filtered points, but also **below** or **next to** those points.
  ::

scale: an optional multiplier by which to scale the resulting shape.
  The default is `1` for no scaling.

expand: a number in mm's by which to expand (or shrink, if the number is negative) the current outline.
  Differs from `scale`ing because it draws and external (or internal) "outline" for the starting shape, thereby usually changing the shape itself, too, not just its size.
  For more info, see the relevant [Maker.JS docs](https://maker.js.org/docs/advanced-drawing/#Expanding%20paths).

joints: a companion to `expand`, specifying which type of treatment to apply to the joints during expansion/shrinking.
  - `0` or `round` means the corners will be rounded (thereby having **zero** joints);
  - `1` or `pointy` means the corners will stay (thereby still having **one** joint); and
  - `2` or `beveled` means the corners will get beveled (thereby having **two** joints).

fillet: this number (if greater than the default zero) triggers a filleting operation on the (almost-)completed part and rounds its corners with the given radius.
  If the radius is larger than either of the corner's neighboring line segments, that corner is skipped.
  ::tip
  Once a corner is filleted, it won't be filleted again, so it's safe to apply a `fillet` with increasingly smaller radii to catch every sharp corner if desired.
  ::
```

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

### Outline Shape Attributes

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/outlines.md

Defines the 'outline' primitive for reusing existing outlines. It requires a 'name' attribute and optionally accepts an 'origin' anchor to specify the placement origin.

```ergogen
outline:
  name: string (mandatory)
  origin: anchor (optional)
```

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

### Ergogen Output Case Format

Source: https://github.com/ergogen/ergogen-docs/blob/main/docs/formats.md

Currently, Ergogen outputs cases in JSCAD format.

```jscad
function main() {
  return cube({size: 10});
}
```