enable deeper linking into various schemas

and fixed a few typos

Signed-off-by: Taylor Silva <dev@taydev.net>

Author: taylorsilva

docs/docs/jobs.md

@@ -14,14 +14,17 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
 
 ??? warning "**`name`**: [`identifier`](config-basics.md#identifier-schema) (required)"
 
+    ### `name`
     The name of the job. This should be short; it will show up in URLs. If you want to rename a job, use `job.old_name`.
 
 ??? warning "`steps`: [`[step]`](steps/index.md) (required)"
 
+    ### `steps`
     The sequence of [steps](steps/index.md) to execute.
 
 ??? info "**`old_name`**: [`identifier`](config-basics.md#identifier-schema)"
 
+    ### `old_name`
     The old name of the job. If configured, the history of old job will be inherited to the new one. Once the pipeline 
     is set, this field can be removed as the builds have been transfered.
 
@@ -48,10 +51,12 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
 
 ??? info "**`serial`**: [`boolean`](config-basics.md#boolean-schema)"
 
+    ### `serial`
     _Default `false`_. If set to `true`, builds will queue up and execute one-by-one, rather than executing in parallel.
 
 ??? info "**`serial_groups`**: [`[identifier]`](config-basics.md#identifier-schema)"
 
+    ### `serial_groups`
     _Default `[]`_. When set to an array of arbitrary tag-like strings, builds of this job and other jobs referencing 
     the same tags will be serialized.
 
@@ -82,11 +87,13 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
 
 ??? info "**`max_in_flight`**: [`number`](config-basics.md#number-schema)"
 
+    ### `max_in_flight`
     If set, specifies a maximum number of builds to run at a time. If `serial` or `serial_groups` are set, they take 
     precedence and force this value to be `1`.
 
 ??? info "**`build_log_retention`**: [`build_log_retention_policy`](#build_log_retention_policy-schema)"
 
+    ### `build_log_retention`
     Configures the retention policy for build logs. This is useful if you have a job that runs often but after some 
     amount of time the logs aren't worth keeping around.
 
@@ -117,7 +124,7 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
         the `builds` configuration. And if they all happened to have failed, the `minimum_succeeded_builds` will keep 
         around at least one successful build. All policies operate independently.
 
-    ### `build_log_retention_policy` schema
+    #### `build_log_retention_policy` schema
 
     ??? info "**`days`**: [`number`](config-basics.md#number-schema)"
 
@@ -138,6 +145,7 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
 
 ??? info "`public`: [`boolean`](config-basics.md#boolean-schema)"
 
+    ### `public`
     _Default `false`_. If set to `true`, the build log of this job will be viewable by unauthenticated users. 
     Unauthenticated users will always be able to see the inputs, outputs, and build status history of a job. This is 
     useful if you would like to expose your pipeline publicly without showing sensitive information in the build log.
@@ -150,37 +158,44 @@ A pipeline's jobs are listed under [`pipeline.jobs`](pipelines/index.md#pipeline
 
 ??? info "`disable_manual_trigger`: [`boolean`](config-basics.md#boolean-schema)"
 
+    ### `disable_manual_trigger`
     _Default `false`_. If set to `true`, manual triggering of the job (via the web UI or 
     [`fly trigger-job`](#fly-trigger-job)) will be disabled.
 
 ??? info "`interruptible`: [`boolean`](config-basics.md#boolean-schema)"
 
+    ### `interruptible`
     _Default `false`_. Normally, when a worker is shutting down it will wait for builds with containers running on that 
     worker to finish before exiting. If this value is set to `true`, the worker will not wait on the builds of this job.
     You may want this if you have a self-deploying Concourse or long-running-but-low-importance jobs.
 
 ??? info "`on_success`: [`step`](steps/index.md)"
 
+    ### `on_success`
     Step to execute when the job succeeds. Equivalent to the [`on_success`](steps/modifier-and-hooks/on-success.md) 
     hook.
 
 ??? info "`on_failure`: [`step`](steps/index.md)"
 
+    ### `on_failure`
     Step to execute when the job fails. Equivalent to the [`on_failure`](steps/modifier-and-hooks/on-failure.md) 
     hook.
 
 ??? info "`on_error`: [`step`](steps/index.md)"
 
+    ### `on_error`
     Step to execute when the job errors. Equivalent to the [`on_error`](steps/modifier-and-hooks/on-error.md) 
     hook.
 
 ??? info "`on_abort`: [`step`](steps/index.md)"
 
+    ### `on_abort`
     Step to execute when the job aborts. Equivalent to the [`on_abort`](steps/modifier-and-hooks/on-abort.md) 
     hook.
 
 ??? info "`ensure`: [`step`](steps/index.md)"
 
+    ### `ensure`
     Step to execute regardless of whether the job succeeds, fails, errors, or aborts. Equivalent to the 
     [`ensure`](steps/modifier-and-hooks/ensure.md) hook.
 

docs/docs/pipelines/index.md

@@ -17,19 +17,23 @@ conform to the following schema:
 
 ??? warning "**`jobs`**: [`[job]`](../jobs.md#job-schema) (required)"
 
+    ### `jobs`
     A set of [jobs](../jobs.md) for the pipeline to continuously schedule. At least one job is required for 
     a pipeline to be valid.
 
 ??? info "`resources`: [`[resource]`](../resources/index.md#resource-schema)"
 
+    ### `resources`
     A set of resources for the pipeline to continuously check.
 
 ??? info "`resource_types`: [`[resource_type]`](../resource-types/index.md#resource_type-schema)"
 
+    ### `resource_types`
     A set of resource types for resources within the pipeline to use.
 
 ??? info "`var_sources`: [`[var_source]`](../vars.md#var_source-schema)"
 
+    ### `var_sources`
     A set of Var sources for the pipeline to use.
 
 ??? info "`groups`: [`[group]`](#group_config-schema)"

docs/docs/resource-types/index.md

@@ -17,6 +17,7 @@ following schema:
 
 ??? warning "**`name`**: [`identifier`](../config-basics.md#identifier-schema) (required)"
 
+    ### `name`
     The name of the resource type. This should be short and simple. This name will be referenced by 
     [`pipeline.resources`](../pipelines/index.md#pipeline-schema) defined within the same pipeline, and 
     [`task-config.image_resource`](../tasks.md#task-config-schema)s used by tasks running in the pipeline.
@@ -25,6 +26,7 @@ following schema:
 
 ??? warning "**`type`**: [`resource_type.name`](../resource-types/index.md#resource_type-schema) | [`identifier`](../config-basics.md#identifier-schema) (required)"
 
+    ### `type`
     The type of the resource used to provide the resource type's container image.
 
     This is a bit meta. Usually this value will be `registry-image` as the resource type must result in a container 
@@ -35,6 +37,7 @@ following schema:
 
 ??? warning "**`source`**: [`config`](../config-basics.md#config-schema) (required)"
 
+    ### `source`
     The configuration for the resource type's resource. This varies by resource type, and is a black box to Concourse; 
     it is blindly passed to the resource at runtime.
 
@@ -44,6 +47,7 @@ following schema:
 
 ??? info "`privileged`: [`boolean`](../config-basics.md#boolean-schema)"
 
+    ### `privileged`
     _Default `false`_. If set to `true`, the resource's containers will be run with full capabilities, as determined by 
     the worker backend the task runs on.
 
@@ -57,22 +61,26 @@ following schema:
 
 ??? info "`params`: [`config`](../config-basics.md#config-schema)"
 
+    ### `params`
     Arbitrary config to pass when running the [`get` step](../steps/get.md) to fetch the resource type's image. This is 
     equivalent to [`get` step `params`](../steps/get.md#get-step).
 
 ??? info "`check_every`: [`duration`](../config-basics.md#duration-schema)"
 
+    ### `check_every`
     _Default `1m`_. The interval on which to check for new versions of the resource. Acceptable interval options are 
     defined by the [time.ParseDuration function](https://golang.org/pkg/time/#ParseDuration).
 
 ??? info "`tags`: [`[string]`](../config-basics.md#string-schema)"
 
+    ### `tags`
     _Default `[]`_. A list of tags to determine which workers the checks will be performed on. You'll want to specify 
     this if the source is internal to a worker's network, for example. See also 
     [`tags`](../steps/modifier-and-hooks/tags.md)
 
 ??? info "`defaults`: [`config`](../config-basics.md#config-schema)"
 
+    ### `defaults`
     The default configuration for the resource type. This varies by resource type, and is a black box to Concourse; it 
     is merged with (duplicate fields are overwritten by) [`resource.source`](../resources/index.md#resource-schema) and 
     passed to the resource at runtime.
@@ -129,7 +137,7 @@ following schema:
         ```
 
     Alternatively, the web node can be configured to use 
-    [defaults for base resource types](../install/running-web.md#configuring-defaults-for-resource-types)
+    [defaults for base resource types](../install/running-web.md#configuring-defaults-for-resource-types).
 
 ---
 

docs/docs/resources/index.md

@@ -20,15 +20,18 @@ schema.
 
 ??? warning "**`name`**: [`identifier`](../config-basics.md#identifier-schema) (required)"
 
+    ### `name`
     The name of the resource. This should be short and simple. This name will be referenced by 
     [build plans](../steps/index.md) of jobs in the pipeline.
 
 ??? warning "**`type`**: [`resource_type.name`](../resource-types/index.md#resource_type-schema) (required)"
 
+    ### `type`
     The [resource type](../resource-types/index.md) implementing the resource.
 
 ??? warning "**`source`**: [`config`](../config-basics.md#config-schema) (required)"
 
+    ### `source`
     The configuration for the resource. This varies by resource type, and is a black box to Concourse; it is blindly 
     passed to the resource at runtime.
 
@@ -42,6 +45,7 @@ schema.
 
 ??? info "**`old_name`**: [`identifier`](../config-basics.md#identifier-schema)"
 
+    ### `old_name`
     The old name of the resource. If configured, the history of the old resource will be inherited to the new one. Once 
     the pipeline is set, this field can be removed as the history has been transferred.
 
@@ -71,11 +75,13 @@ schema.
 
 ??? info "`icon`: [`string`](../config-basics.md#string-schema)"
 
+    ### `icon`
     The name of a [Material Design icon](https://materialdesignicons.com/) to show next to the resource name in the web 
     UI. For example, `github`.
 
 ??? info "`version`: [`version`](../config-basics.md#version-schema)"
 
+    ### `version`
     A version to pin the resource to across the pipeline. This has the same effect as setting 
     [`get` step `version`](../steps/get.md#get-step) on every `get` step referencing the resource.
 
@@ -85,6 +91,7 @@ schema.
 
 ??? info "`check_every`: [`duration`](../config-basics.md#duration-schema) | `never`"
 
+    ### `check_every`
     _Default `1m`_. The interval on which to check for new versions of the resource. Acceptable interval options are 
     defined by the [time.ParseDuration function](https://golang.org/pkg/time/#ParseDuration).
 
@@ -93,17 +100,20 @@ schema.
 
 ??? info "`check_timeout`: [`duration`](../config-basics.md#duration-schema)"
 
+    ### `check_timeout`
     _Default `1h`_. The time limit on checking new versions of resources. Acceptable interval options are defined by the
     [time.ParseDuration function](https://golang.org/pkg/time/#ParseDuration).
 
 ??? info "`expose_build_created_by`: [`boolean`](../config-basics.md#boolean-schema)"
 
+    ### `expose_build_created_by`
     _Default `false`_. If set to `true`, environment variable 
     [`BUILD_CREATED_BY`](../resource-types/implementing.md#metadata) will be available in the metadata of a 
     [`put` step](../steps/put.md). This field is not made available to the [`get` step](../steps/get.md).
 
 ??? info "`tags`: [`[string]`](../config-basics.md#string-schema)"
 
+    ### `tags`
     _Default `[]`_. A list of tags to determine which workers the checks will be performed on. You'll want to specify 
     this if the source is internal to a worker's network, for example.
 
@@ -115,6 +125,7 @@ schema.
 
 ??? info "`public`: [`boolean`](../config-basics.md#boolean-schema)"
 
+    ### `public`
     _Default `false`_. If set to `true`, the metadata for each version of the resource will be viewable by 
     unauthenticated users (assuming the pipeline has been [exposed](../auth-and-teams/exposing.md)).
 
@@ -128,6 +139,7 @@ schema.
 
 ??? info "`webhook_token`: [`string`](../config-basics.md#string-schema)"
 
+    ### `webhook_token`
     If specified, web hooks can be sent to trigger an immediate _check_ of the resource, specifying this value as a 
     primitive form of authentication via query params.
 

docs/docs/steps/get.md

@@ -8,6 +8,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? warning "**`get`**: [`resource.name`](../resources/index.md#resource-schema) | [`identifier`](../config-basics.md#identifier-schema) (required)"
 
+    ### `get`
     The fetched bits will be registered in the build's artifact namespace under the given identifier. Subsequent 
     [`task` step](task.md) and [`put` step](put.md) which list the identifier as an input will have a copy of the bits 
     in their working directory.
@@ -47,6 +48,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? info "**`resource`**: [`resource.name`](../resources/index.md#resource-schema)"
 
+    ### `resource`
     _Defaults to the value of `get`_. The resource to fetch, as configured in 
     [`pipeline.resources`](../pipelines/index.md#pipeline-schema).
 
@@ -85,6 +87,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? info "**`passed`**: [`[job.name]`](../jobs.md#job-schema)"
 
+    ### `passed`
     When specified, only the versions of the resource that made it through the given list of jobs (AND-ed together) will
     be considered when triggering and fetching.
 
@@ -165,6 +168,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? info "**`params`**: [`config`](../config-basics.md#config-schema)"
 
+    ### `params`
     Arbitrary configuration to pass to the resource. Refer to the resource type's documentation to see what it supports.
 
     ??? example "Fetching with params"
@@ -180,7 +184,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
               - put: cyberdeck
                 params:
                   file: cyberdeck/version_to_put.txt
-        
+
         
         resources:
           - name: cyberdeck
@@ -189,6 +193,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? info "**`trigger`**: [`boolean`](../config-basics.md#boolean-schema)"
 
+    ### `trigger`
     _Default `false`_. If set to `true`, new builds of the job will be automatically created when a new version for this
     input becomes available.
 
@@ -226,6 +231,7 @@ Fetches a version of a [resource](../resources/index.md). Expand each section be
 
 ??? info "**`version`**: `latest` | `every` | [`version`](../config-basics.md#version-schema)"
 
+    ### `version`
     _Default `latest`_. The version of the resource to fetch.
 
     If set to `latest`, scheduling will just find the latest available version of a resource and use it, allowing 

docs/docs/steps/load-var.md

@@ -10,6 +10,7 @@ details and examples.
 
 ??? warning "**`load_var`**: [`identifier`](../config-basics.md#identifier-schema) (required)"
 
+    ### `load_var`
     The identifier will be the name of var, available to subsequent steps as a [local build var](../vars.md#local-var).
 
     ??? example "Loading a simple value as a var"
@@ -27,7 +28,7 @@ details and examples.
               - put: img
                 params:
                   version: ((.:version))
-        
+
         
         resources:
           - name: examples
@@ -47,10 +48,12 @@ details and examples.
 
 ??? warning "**`file`**: [`file-path`](../config-basics.md#file-path-schema) (required)"
 
+    ### `file`
     The path to a file whose content shall be read and used as the var's value.
 
 ??? info "**`format`**: `json` | `yaml` | `yml` | `trim` | `raw`"
 
+    ### `format`
     The format of the file's content.
 
     If unset, Concourse will try to detect the format from the file extension. If the file format cannot be determined, 
@@ -87,7 +90,7 @@ details and examples.
               - put: img
                 params:
                   version: "((.:version.hello))-((.:version.number))"
-        
+
         
         resources:
           - name: examples
@@ -104,5 +107,6 @@ details and examples.
 
 ??? info "**`reveal`**: [`boolean`](../config-basics.md#boolean-schema)"
 
+    ### `reveal`
     _Default `false`_. If set to `true`, allow the var's content to be printed in the build output even with secret 
     redaction enabled.