Merge pull request #151 from nickhammond/yml-anchors

Add a full example of using yml anchors

_data/docs.yml

@@ -11,6 +11,8 @@
       url: /docs/configuration/accessories/
     - title: "Aliases"
       url: /docs/configuration/aliases/
+    - title: "Anchors"
+      url: /docs/configuration/anchors/
     - title: "Booting"
       url: /docs/configuration/booting/
     - title: "Builders"

docs/configuration/anchors.md

@@ -0,0 +1,30 @@
+---
+title: Anchors
+---
+
+# Anchors
+
+You can re-use parts of your Kamal configuration by defining them as anchors and referencing them with aliases.
+
+For example, you might need to define a shared healthcheck for multiple worker roles. Anchors
+begin with `x-` and are defined at the root level of your deploy.yml file.
+
+```yaml
+x-worker-healthcheck: &worker-healthcheck
+  health-cmd: bin/worker-healthcheck
+  health-start-period: 5s
+  health-retries: 5
+  health-interval: 5s
+```
+
+To use this anchor in your deploy configuration, reference it via the alias.
+
+```yaml
+servers:
+  worker:
+    hosts:
+      - 867.53.0.9
+    cmd: bin/jobs
+    options:
+      <<: *worker-healthcheck
+```

docs/configuration/overview.md

@@ -16,15 +16,15 @@ e.g., `kamal deploy -d staging`.
 In this case, the configuration will also be read from `config/deploy.staging.yml`
 and merged with the base configuration.
 
-## [Extensions](#extensions)
+## [Anchors](#anchors)
 
 Kamal will not accept unrecognized keys in the configuration file.
 
 However, you might want to declare a configuration block using YAML anchors
 and aliases to avoid repetition.
 
 You can prefix a configuration section with `x-` to indicate that it is an
-extension. Kamal will ignore the extension and not raise an error.
+anchor. Kamal will ignore the anchor and not raise an error. See [Anchors](../anchors) for more information.
 
 ## [The service name](#the-service-name)