docs: link and formatting updates (#1290)

* Doc link and formatting updates.

* GitHub checkout action branch rename.

* Cross-link for custom functions to core functions; also trying this as a fix for MD link check.

* Fixed link typo.

.github/workflows/markdown-links.yml

@@ -10,7 +10,7 @@ jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@main
     - uses: gaurav-nelson/github-action-markdown-link-check@master
       with:
         folder-path: 'docs'

README.md

@@ -15,7 +15,7 @@ A flexible JSON/YAML linter, with out of the box support for OpenAPI v2/v3 and A
   - OpenAPI v2 _and_ v3 documents
   - AsyncAPI v2 documents
 - Use JSON path to apply rules to specific parts of your objects
-- Built-in set of functions to help [create custom rules](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/rulesets.md#adding-a-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
+- Built-in set of functions to help [create custom rules](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/3-rulesets.md#adding-a-rule). Functions include pattern checks, parameter checks, alphabetical ordering, a specified number of characters, provided keys are present in an object, etc.
 - Create custom functions for advanced use cases
 - Validate JSON with [Ajv](https://www.npmjs.com/package/ajv)
 
@@ -33,13 +33,13 @@ npm install -g @stoplight/spectral
 yarn global add @stoplight/spectral
 ```
 
-Find more [installation methods](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/installation.md) in our documentation.
+Find more [installation methods](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/2-installation.md) in our documentation.
 
 This package is [Treeware](https://treeware.earth) so if you would like to thank us for creating it, we ask that you [**buy the world a tree**](https://plant.treeware.earth/stoplightio/spectral).
 
 ## Documentation
 
-Take a look at our [getting started documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/concepts.md), then peek through some of our guides:
+Take a look at our [getting started documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/getting-started/1-concepts.md), then peek through some of our guides:
 
 - [Different Workflows](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/1-workflows.md) - When and where should you use Spectral? Editors, Git-hooks, Continuous Integration, GitHub Actions, wherever you like!
 - [Using the command-line interface](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/guides/2-cli.md) - Quickest way to get going with Spectral is in the CLI.

docs/getting-started/concepts.md → docs/getting-started/1-concepts.md

@@ -2,9 +2,9 @@
 
 The power of integrating linting into the design-first workflow, or any workflow which involves API descriptions, is often overlooked.
 
-Linting is not just about checking to see if some OpenAPI or JSON Schema documents are technically correct according to the specifications, they are for enforcing style guides! These style guides, much like eslint, can help catch a lot more than just "invalid syntax".
+Linting is not just about checking to see if some OpenAPI or JSON Schema documents are technically correct according to the specifications, they are for enforcing style guides! These style guides, much like eslint, can help catch a lot more than just "invalid syntax."
 
-To achieve this functionality, Spectral has three key concepts: "Rulesets", "Rules", and "Functions".
+To achieve this functionality, Spectral has three key concepts: "Rulesets", "Rules", and "Functions."
 
 - **Rulesets** act as a container for rules and functions.
 - **Rules** filter your object down to a set of target values, and specify the function that is used to evaluate those values.
@@ -18,6 +18,6 @@ Rules can be comprised of one of more functions, to facilitate any style guide.
 - Tags must be plural
 - Tags must be singular
 
-Spectral comes bundled with a [bunch of functions](../reference/functions.md) and default style guides for [OpenAPI v2 and v3](./openapi.md) and [AsyncAPI v2](./asyncapi.md), which you can extend, cherry-pick, or disable entirely.
+Spectral comes bundled with a [bunch of functions](../reference/functions.md) and default style guides for [OpenAPI v2 and v3](./4-openapi.md) and [AsyncAPI v2](./5-asyncapi.md), which you can extend, cherry-pick, or disable entirely.
 
-Learn more about [rulesets](./rulesets.md).
+[Learn more about rulesets](./3-rulesets.md).

docs/getting-started/installation.md → docs/getting-started/2-installation.md

@@ -1,4 +1,3 @@
-
 # Installation
 
 For many, the easiest way to install Spectral is as a node module.
@@ -13,7 +12,7 @@ If you are a Yarn user:
 yarn global add @stoplight/spectral
 ```
 
-## Executable binaries
+## Executable Binaries
 
 For users without Node and/or NPM/Yarn, we provide standalone packages for [all major platforms](https://github.com/stoplightio/spectral/releases). The quickest way to install the appropriate package for your operating system is via this shell script:
 
@@ -28,7 +27,7 @@ Note, the binaries do _not_ auto-update, so you will need to run it again to ins
 Spectral is also available as a Docker image, which can be handy for all sorts of things, like if you're contributing code to Spectral, want to integrate it into your CI build.
 
 ```bash
-docker run --rm -it stoplight/spectral lint "${url}"`
+docker run --rm -it stoplight/spectral lint "${url}"
 ```
 
 If the file you want to lint is on your computer, you'll need to mount the directory where the file resides as a volume

docs/getting-started/rulesets.md → docs/getting-started/3-rulesets.md

@@ -6,7 +6,7 @@ These rules are taking parameters, and calling functions on certain parts of ano
 
 ## Anatomy of a Ruleset
 
-A ruleset is a JSON or YAML file (often the file will be called `.spectral.yaml`), and there are two main parts.
+A ruleset is a JSON or YAML file ([often the file will be called `.spectral.yaml`](../guides/2-cli.md#using-a-ruleset-file)), and there are two main parts.
 
 ### Rules
 
@@ -121,24 +121,7 @@ Custom formats can be registered via the [JS API](../guides/3-javascript.md), bu
 
 Spectral comes with two rulesets included:
 
- - `spectral:oas` - OpenAPI v2/v3 rules
- - `spectral:asyncapi` - AsyncAPI v2 rules
+- `spectral:oas` - [OpenAPI v2/v3 rules](./4-openapi.md)
+- `spectral:asyncapi` - [AsyncAPI v2 rules](./5-asyncapi.md)
 
 You can also make your own: read more about [Custom Rulesets](../guides/4-custom-rulesets.md).
-
-## Documentation URL
-
-Optionally provide a documentation URL to your ruleset in order to help end-users find more information about various warnings. Result messages will sometimes be more than enough to explain what the problem is, but it can also be beneficial to explain _why_ a message exists, and this is a great place to do that.
-
-Whatever you link you provide, the rule name will be appended as an anchor.
-
-Given the following `documentationUrl` [`https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/openapi-rules.md`](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/openapi-rules.md), an example URL for `info-contact` rule would look as follows [`https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/openapi-rules.md#info-contact`](https://stoplight.io/p/docs/gh/stoplightio/spectral/docs/reference/openapi-rules.md#info-contact).
-
-```yaml
-documentationUrl: https://www.example.com/docs/api-ruleset.md
-
-rules:
-  # ...
-```
-
-If no `documentationUrl` is provided, no links will show up, and users will just have to rely on the error messages to figure out how the errors can be fixed.

docs/guides/1-workflows.md

@@ -29,7 +29,7 @@ For example if the API has a bunch of URLs with underscores, then becoming consi
 
 Folks will forget to run Spectral, and that means they can commit broken or (low quality) documents. Adding a git commit hook can be a simple solution to this using something like [Husky](https://github.com/typicode/husky).
 
-```
+```jsonc
 // package.json
 {
   "husky": {
@@ -48,7 +48,7 @@ See our [CLI documentation](./2-cli.md) to see what other arguments and options
 
 Running Spectral on CI servers is just a case of doing what you'd do in the CI.
 
-``` yaml
+```yaml
 version: 2
 jobs:
   build:

docs/guides/2-cli.md

@@ -1,6 +1,6 @@
 # Spectral CLI
 
-Once installed, Spectral can be run via the command-line:
+[Once installed](../getting-started/2-installation.md), Spectral can be run via the command-line:
 
 ```bash
 spectral lint petstore.yaml
@@ -20,7 +20,7 @@ spectral lint ./reference/**/*.oas*.{json,yml,yaml}
 
 Other options include:
 
-``` text
+```text
   --version                    Show version number                                          [boolean]
   --help                       Show help                                                    [boolean]
   --encoding, -e               text encoding to use                        [string] [default: "utf8"]
@@ -41,9 +41,12 @@ Other options include:
 
 The Spectral CLI supports loading documents as YAML or JSON, and validation of OpenAPI v2/v3 documents via our built-in ruleset.
 
-You can also provide your own ruleset file. By default, the Spectral CLI will look for a ruleset file called `.spectral.yml` or `.spectral.json` in the current working directory. You can tell spectral to use a different file by using the `--ruleset` CLI option.
+## Using a Ruleset File
+
+If you don't specify a ruleset file with the `--ruleset` parameter, the Spectral CLI will look for a ruleset file called `.spectral.yml`, `.spectral.yaml`, or `.spectral.json` in the current working directory. If no ruleset is specified and no default ruleset file is found, the built-in rulesets will be used.
+
+Here you can build a [custom ruleset](../getting-started/3-rulesets.md), or extend and modify our core rulesets:
 
-Here you can build a [custom ruleset](../getting-started/rulesets.md), or extend and modify our core rulesets:
 - [OpenAPI ruleset](../reference/openapi-rules.md)
 - [AsyncAPI ruleset](../reference/asyncapi-rules.md)
 
@@ -61,7 +64,7 @@ To have requests made from Spectral be proxied through a server, you'd need to s
 
 `PROXY=<<PROXY_SERVER_ADDRESS>> spectral lint spec.yaml`
 
-## Custom $ref resolving
+## Custom $ref Resolving
 
 If you want to customize $ref resolving, you can leverage `--resolver` flag and pass a path to the JS file exporting a custom instance of json-ref-resolver Resolver.
 
@@ -79,5 +82,4 @@ module.exports = new Resolver({
 });
 ```
 
-
-You can learn more about $ref resolving in the [JS section](./3-javascript.md#using-custom-resolver).
+You can learn more about `$ref` resolving in the [JS section](./3-javascript.md#using-custom-resolver).

docs/guides/3-javascript.md

@@ -4,7 +4,7 @@ The Spectral CLI is a thin wrapper around a JavaScript (TypeScript) API, which c
 
 Assuming it has been installed as a Node module via NPM/Yarn, it can be used to lint YAML and JSON documents from a string, or from an object.
 
-## Linting a YAML string
+## Linting a YAML String
 
 ```js
 const { Spectral, Document, Parsers } = require('@stoplight/spectral');
@@ -23,7 +23,7 @@ spectral
 ```
 
 Please note that by default Spectral supports YAML 1.2 with merge keys extension.
-As recommended by the [spec](https://yaml.org/spec/1.2/spec.html#id2804923), tags are resolved according to the "Core Schema".
+As recommended by the [spec](https://yaml.org/spec/1.2/spec.html#id2804923), tags are resolved according to the "Core Schema."
 
 This will run Spectral with no formats, rules or functions, so it's not going to do anything besides $ref resolving.
 Find out how to add formats, rules and functions below.
@@ -89,7 +89,7 @@ spectral.registerFormat('json-schema-draft7', isJSONSchemaDraft7);
 spectral.registerFormat('json-schema-2019-09', isJSONSchemaDraft2019_09);
 ```
 
-Learn more about predefined formats in the (ruleset documentation)[../getting-started/rulesets.md#formats].
+Learn more about predefined formats in the [ruleset documentation](../getting-started/3-rulesets.md#formats).
 
 ## Loading Rules
 
@@ -153,7 +153,7 @@ spectral.run(myOpenApiDocument)
 
 ## Advanced
 
-### Creating a custom format
+### Creating a Custom Format
 
 Spectral supports two core formats: `oas2` and `oas3`. Using `registerFormat` you can add support for auto-detecting other formats. You might want to do this for a ruleset which is run against multiple major versions of description format like RAML v0.8 and v1.0.
 
@@ -192,9 +192,9 @@ spectral
   });
 ```
 
-### Using a proxy
+### Using a Proxy
 
-Spectral supports http(s) proxies when fetching remote schemas and rulesets.
+Spectral supports HTTP(S) proxies when fetching remote schemas and rulesets.
 
 ```js
 const { Spectral } = require('@stoplight/spectral');
@@ -205,7 +205,7 @@ spectral.loadRuleset('https://example.org/my-rules')
 // lint as usual - $refs and rules will be requested using the proxy
 ```
 
-### Using custom resolver
+### Using a Custom Resolver
 
 Spectral lets you provide any custom $ref resolver. By default, http(s) and file protocols are resolved, relatively to
 the document Spectral lints against. If you'd like support any additional protocol or adjust the resolution, you are
@@ -249,7 +249,7 @@ The custom resolver we've just created will resolve all remote file refs relativ
 
 More on that can be found in the [json-ref-resolver repo](https://github.com/stoplightio/json-ref-resolver).
 
-### Using custom de-duplication strategy
+### Using a Custom De-duplication Strategy
 
 By default, Spectral will de-duplicate results based on the result code and document location. You can customize this
 behavior with the `computeFingerprint` option. For example, here is the default fingerprint implementation:

docs/guides/4-custom-rulesets.md

@@ -19,7 +19,10 @@ rules:
 
 Spectral has [built-in functions](../reference/functions.md) such as `truthy` or `pattern`, which can be used to power rules.
 
-By default, Spectral processes each rule on "resolved document" (a file where all `$ref`s have been resolved. If you would like to have an original input supplied to your rule, you can place `resolved` property as follows:
+<!-- theme: info -->
+> Spectral processes each rule on "resolved document" (a file where all `$ref` entries have been resolved). If your rule needs to access `$ref` values, you must set `resolved: false` on your rule.
+
+Here's an eample of a rule that can access `$ref` values:
 
 ```yaml
 rules:
@@ -33,9 +36,9 @@ rules:
       function: truthy
 ```
 
-You might find `resolved` useful if your rule requires access to `$ref` values specifically, for example if you want to enforce conventions on the folder structure used for [splitting up documents](https://stoplight.io/blog/keeping-openapi-dry-and-portable/).
+You might find `resolved: false` useful if your rule requires access to `$ref` values specifically, for example if you want to enforce conventions on the folder structure used for [splitting up documents](https://stoplight.io/blog/keeping-openapi-dry-and-portable/).
 
-In most cases, you will want to operate on resolved document.
+**In most cases, you will want to operate on a resolved document.**
 
 ### Given
 
@@ -52,7 +55,9 @@ The default value is `warn`.
 
 ### Then
 
-The Then part of the rules explains what to do with the `given` JSONPath, and involves two required keywords:
+The `then` part of the rule explains which function to apply to the `given` JSONPath. The function you apply [may be one of the core functions](../reference/functions.md) or it may be [a custom function](./5-custom-functions.md).
+
+`then` has two required keywords:
 
 ```yaml
 then:
@@ -71,7 +76,7 @@ then:
     match: '^[0-9]+$'
 ```
 
-The above pattern based rule would error on `456avbas` as it is not numeric.
+The above [`pattern` based rule](../reference/functions.md#pattern) would error on `456avbas` as it is not numeric.
 
 ```yaml
 responses:
@@ -100,7 +105,7 @@ This provides a new description, and changes recommended to true, but anything c
 
 If you're just looking change the severity of the rule, there is a handy shortcut.
 
-### Changing rule severity
+## Changing Rule Severity
 
 Maybe you want to use the rules from the `spectral:oas` ruleset, but instead of `operation-2xx-response` triggering an error you'd like it to trigger a warning instead.
 
@@ -112,9 +117,9 @@ rules:
 
 Available severity levels are `error`, `warn`, `info`, `hint`, and `off`.
 
-## Disabling rules
+## Disabling Rules
 
-This example shows the opposite of the "Enabling Specific rules" example. Sometimes you might want to enable all rules by default, and disable a few.
+This example shows the opposite of the "Enabling Specific Rules" example. Sometimes you might want to enable all rules by default, and disable a few.
 
 ```yaml
 extends: [[spectral:oas, all]]
@@ -157,6 +162,33 @@ message: "{{value}} is greater than 0"
 message: "{{path}} cannot point at remote reference"
 ```
 
+## Documentation URL
+
+Optionally provide a documentation URL to your ruleset in order to help end-users find more information about various warnings. Result messages will sometimes be more than enough to explain what the problem is, but it can also be beneficial to explain _why_ a message exists, and this is a great place to do that.
+
+Whatever you link you provide, the rule name will be appended as an anchor.
+
+```yaml
+extends: spectral:oas
+documentationUrl: https://www.example.com/docs/api-ruleset.md
+rules:
+  tag-description:
+    description: Please provide a description for each tag.
+    given: $.tags[*]
+    then:
+      field: description
+      function: truthy
+
+```
+
+In this example, violations of the `tag-description` rule would indicate `https://www.example.com/docs/api-ruleset.md#tag-description` as the location for finding out more about the rule.
+
+If no `documentationUrl` is provided, no links will show up, and users will just have to rely on the error messages to figure out how the errors can be fixed.
+
+## Core Functions
+
+Several functions [are provided by default](../reference/functions.md) for your rules.
+
 ## Custom Functions
 
-Learn more about [custom functions](../guides/5-custom-functions.md).
+If none of the [core functions](../reference/functions.md) do what you want, you can [write your own custom functions](./5-custom-functions.md).

docs/guides/5-custom-functions.md

@@ -1,6 +1,6 @@
 # Custom Functions
 
-If the built-in functions are not enough for your [custom ruleset](../getting-started/rulesets.md), Spectral allows you to write and use your own custom functions.
+If the built-in functions are not enough for your [custom ruleset](../getting-started/3-rulesets.md), Spectral allows you to write and use your own custom functions.
 
 Create a directory to contain your new functions. By default `functions/` is assumed.
 

docs/guides/6-exceptions.md

@@ -65,6 +65,5 @@ An example with more path segments: the location for a `get` method from a
 `/todos/{todo_id}/labels` path in an openapi document `/root/here.yaml`
 would be expressed as `/root/here.yaml#/paths/~1todos~1{todo_id}~1labels/get`.
 
-
 <!-- theme: info -->
 > Running Spectral CLI with the `--format json` parameter is pretty useful to find out the path segments of each result.