Create markdown-lint.yml (#2534)

* Create markdown-lint.yml

* Fix lint errors.

.github/workflows/markdown-lint.yml

@@ -0,0 +1,22 @@
+name: Markdown Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  markdown-lint:
+    name: Markdown Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: |
+          npm install -g [email protected]
+          markdownlint --config .markdownlint.yaml '**/*.md'

.markdownlint.yaml

@@ -0,0 +1,3 @@
+"default": true # Default state for all rules
+"MD013": false # Disable rule for line length
+"MD033": false # Disable rule banning inline HTML

docs/README.md

@@ -10,7 +10,7 @@ cargo install mdbook
 
 To set up and build the book locally, you must also have `mdbook-forc-documenter` preprocessor and relevant forc plugins installed.
 
-If you wish to make changes to the `Commands` or `Plugins` chapters, please read the [next section](#Generating-documentation-for-Forc-commandsplugins) first.
+If you wish to make changes to the `Commands` or `Plugins` chapters, please read the [next section](#generating-documentation-for-forc-commandsplugins) first.
 
 From the project root, install `mdbook-forc-documenter`:
 

docs/src/advanced/generic_types.md

@@ -41,7 +41,7 @@ fn get_hashmap_key<T>(Key : T) -> b256
 }
 ```
 
-*`where` clauses are still [work-in-progress](https://github.com/FuelLabs/sway/issues/970), so some `where` statements shown may not be fully implemented.*
+_`where` clauses are still [work-in-progress](https://github.com/FuelLabs/sway/issues/970), so some `where` statements shown may not be fully implemented._
 
 Of course, our `noop()` function is not useful. Often, a programmer will want to declare functions over types which satisfy certain traits.
 For example, let's try to implement the successor function, `successor()`, for all numeric types.

docs/src/advanced/trait_constraints.md

@@ -1,3 +1,3 @@
 # Trait Constraints
 
-Trait constraints on generics are currently a work in progress.
+Trait constraints on generics are currently a work in progress.

docs/src/basics/blockchain_types.md

@@ -70,7 +70,7 @@ A `match` statement can be used to return to an `Address` or `ContractId` as wel
 {{#include ../../../examples/identity/src/main.sw:different_executions}}
 ```
 
-A common use case for `Identity` is for access control. The use of `Identity` uniquely allows both `ContractId` and `Address` to have access control inclusively. 
+A common use case for `Identity` is for access control. The use of `Identity` uniquely allows both `ContractId` and `Address` to have access control inclusively.
 
 ```sway
 {{#include ../../../examples/identity/src/main.sw:access_control_with_identity}}

docs/src/basics/structs_tuples_and_enums.md

@@ -4,7 +4,7 @@
 
 Structs in Sway are a named grouping of types. You may also be familiar with structs via another name: _product types_. Sway does not make any significantly unique usages of structs; they are similar to most other languages which have structs. If you're coming from an object-oriented background, a struct is like the data attributes of an object.
 
-Firstly, we declare a struct named `Foo` with two fields. The first field is named `bar` and it accepts values of type `u64`, the second field is named `baz` and it accepts `bool` values. 
+Firstly, we declare a struct named `Foo` with two fields. The first field is named `bar` and it accepts values of type `u64`, the second field is named `baz` and it accepts `bool` values.
 
 ```sway
 {{#include ../../../examples/structs/src/data_structures.sw}}
@@ -30,7 +30,7 @@ Furthermore, multiple variables can be extracted from a struct using the destruc
 
 ### Struct Memory Layout
 
-> **Note** 
+> **Note**
 > This information is not vital if you are new to the language, or programming in general
 
 Structs have zero memory overhead. What that means is that in memory, each struct field is laid out sequentially. No metadata regarding the struct's name or other properties is preserved at runtime. In other words, structs are compile-time constructs. This is the same in Rust, but different in other languages with runtimes like Java.

docs/src/common-collections/storage_map.md

@@ -34,9 +34,12 @@ To insert key-value pairs into a storage map, we can use the `insert` method, as
 
 Note two details here. First, in order to use `insert`, we need to first access the storage map using the `storage` keyword. Second, because `insert` requires _writing_ into storage, a `#[storage(write)]` annotation is required on the ABI function that calls `insert`.
 
-> **Note**: The storage annotation is also required for any private function defined in the contract that tries to insert into the map.
+> **Note**
+> The storage annotation is also required for any private function defined in the contract that tries to insert into the map.
 
-> **Note**: There is no need to add the `mut` keyword when declaring a `StorageMap<K, V>`. All storage variables are mutable by default.
+<!-- markdownlint-disable-line MD028 -->
+> **Note**
+> There is no need to add the `mut` keyword when declaring a `StorageMap<K, V>`. All storage variables are mutable by default.
 
 ## Accessing Values in a Storage Map
 

docs/src/common-collections/storage_vec.md

@@ -32,9 +32,12 @@ To add elements to a storage vector, we can use the `push` method, as shown belo
 
 Note two details here. First, in order to use `push`, we need to first access the vector using the `storage` keyword. Second, because `push` requires accessing storage, a `storage` annotation is required on the ABI function that calls `push`. While it may seem that `#[storage(write)]` should be enough here, the `read` annotation is also required because each call to `push` requires _reading_ (and then updating) the length of the storage vector which is also stored in persistent storage.
 
-> **Note**: The storage annotation is also required for any private function defined in the contract that tries to push into the vector.
+> **Note**
+> The storage annotation is also required for any private function defined in the contract that tries to push into the vector.
 
-> **Note**: There is no need to add the `mut` keyword when declaring a `StorageVec<T>`. All storage variables are mutable by default.
+<!-- markdownlint-disable-line MD028 -->
+> **Note**
+> There is no need to add the `mut` keyword when declaring a `StorageVec<T>`. All storage variables are mutable by default.
 
 ## Reading Elements of Storage Vectors
 

docs/src/forc/commands/index.md

@@ -1 +1,2 @@
+<!-- markdownlint-disable MD041 -->
 Here are a list of commands available to forc:

docs/src/forc/plugins.md

@@ -25,7 +25,7 @@ Running server on http://127.0.0.1:3030
 Server::run{addr=127.0.0.1:3030}: listening on http://127.0.0.1:3030
 ```
 
-You can visit http://127.0.0.1:3030 to check out the network explorer!
+You can visit <http://127.0.0.1:3030> to check out the network explorer!
 
 ## Writing your own plugin
 

docs/src/introduction/installation.md

@@ -28,11 +28,10 @@ Once `fuelup` is installed, `fuelup-init` automatically runs the command below
 fuelup toolchain install latest
 ```
 
-to install the latest Sway toolchain. 
+to install the latest Sway toolchain.
 
 You can run the same command at a later time to update the toolchain.
 
-
 ## Installing from Source
 
 ### Dependencies

docs/src/reference/contributing_to_sway.md

@@ -84,18 +84,18 @@ Pull requests should be linked to at least one issue in the same repo.
 
 If the pull request resolves the relevant issues, and you want GitHub to close these issues automatically after it merged into the default branch, you can use the syntax (`KEYWORD #ISSUE-NUMBER`) like this:
 
-```
+```markdown
 close #123
 ```
 
 If the pull request links an issue but does not close it, you can use the keyword `ref` like this:
 
-```
+```markdown
 ref #456
 ```
 
 Multiple issues should use full syntax for each issue and separate by a comma, like:
 
-```
+```markdown
 close #123, ref #456
 ```

docs/src/sway-program-types/smart_contracts.md

@@ -20,7 +20,7 @@ Let's focus on the ABI declaration and inspect it line-by-line.
 
 ---
 
-In the first line, `abi Wallet {`, we declare the name of this _Application Binary Interface_, or ABI. We are naming this ABI `Wallet`. To import this ABI into either a script for calling or a contract for implementing, you would use 
+In the first line, `abi Wallet {`, we declare the name of this _Application Binary Interface_, or ABI. We are naming this ABI `Wallet`. To import this ABI into either a script for calling or a contract for implementing, you would use
 
 ```sway
 {{#include ../../../examples/wallet_smart_contract/src/main.sw:abi_import}}

docstrings/src/TODO.md

@@ -1,4 +1,4 @@
-Remaining TODO items:
+# Remaining TODO items
 
 1. Design ideal API
 1. Support documenting functions

scripts/highlightjs/README.md

@@ -1,15 +1,15 @@
-## Instructions
+# Instructions
 
 Update "sway.js" file.
 
 Then run:
 
 ```sh
-$ ./build.sh
+./build.sh
 ```
 
 If you are actively developing and testing and want to keep `highlight.js` directory add `keep` in the command
 
 ```sh
-$ ./build.sh keep
+./build.sh keep
 ```

scripts/mdbook-forc-documenter/examples/forc_build.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_completions.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## DISCUSSION
 

scripts/mdbook-forc-documenter/examples/forc_deploy.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_init.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_new.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_parse-bytecode.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_template.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/mdbook-forc-documenter/examples/forc_test.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 
 ## EXAMPLE
 

scripts/prism/README.md

@@ -1,19 +1,19 @@
-## Instructions
+# Instructions
 
 Update "prism-sway.js" file.
 
 Then run:
 
 ```sh
-$ ./build.sh
+./build.sh
 ```
 
 If you are actively developing and testing and want to keep `prism` (repo) directory add `keep` in the command
 
 ```sh
-$ ./build.sh keep
+./build.sh keep
 ```
 
-### Testing
+## Testing
 
 If you want to test it in html, `keep` the "prism" folder, and open "test-suite.html" and start writing Sway.

sway-ir/tests/README.md

@@ -10,9 +10,9 @@ be:
 
 * The single word `all`, indicating all `CALL`s found throughout the input will be inlined.
 * A combination of sizes which are passed to the `optimize::inline::is_small_fn()` function:
-    * `blocks N` to indicate a maximum of `N` allowed blocks constraint.
-    * `instrs N`  to indicate a maximum of `N` allowed instructions constraint.
-    * `stack N` to indicate a maximum of `N` for stack size constraint.
+  * `blocks N` to indicate a maximum of `N` allowed blocks constraint.
+  * `instrs N`  to indicate a maximum of `N` allowed instructions constraint.
+  * `stack N` to indicate a maximum of `N` for stack size constraint.
 
 Any keyword found later in the line will override an earlier parameter.  `all` will override any
 other constraint.

test/src/e2e_vm_tests/test_programs/README.md

@@ -1,4 +1,4 @@
-# Config Driven End To End Testing.
+# Config Driven End To End Testing
 
 Each of the tests in this suite are controlled by a TOML descriptor file which describes how the
 test should be run and what result to expect if any.
@@ -12,11 +12,11 @@ i.e., next to the `Forc.toml` file.  This file may contain a few basic fields.
 
 The `category` field is mandatory and must be one of the following strings:
 
-* `"run"` - The test is compiled and run in a VM.
-* `"run_on_node"` - The test is compiled and run on a local Fuel Core node.
-* `"compile"` - The test is expected to succeed compiling, but isn't run in any way.
-* `"fail"` - The test is expected to fail to compile.
-* `"disabled"` - The test is disabled.
+- `"run"` - The test is compiled and run in a VM.
+- `"run_on_node"` - The test is compiled and run on a local Fuel Core node.
+- `"compile"` - The test is expected to succeed compiling, but isn't run in any way.
+- `"fail"` - The test is expected to fail to compile.
+- `"disabled"` - The test is disabled.
 
 ## expected_result
 
@@ -25,10 +25,10 @@ two fields, `action` and `value`.
 
 The `action` field describe what sort of result to expect:
 
-* `"return"` - An integer value returned by success in the VM.
-* `"return_data"` - An array of bytes returned by the VM.
-* `"result"` - An integer word returned by the Fuel Core node.
-* `"revert"` - An integer value returned by failure in the VM.
+- `"return"` - An integer value returned by success in the VM.
+- `"return_data"` - An array of bytes returned by the VM.
+- `"result"` - An integer word returned by the Fuel Core node.
+- `"revert"` - An integer value returned by failure in the VM.
 
 The `value` field is the actual expected value.  For `"return"`, `"result"` and `"revert"` actions
 it must be an integer.
@@ -50,7 +50,7 @@ be compiled and deployed.  It is important that these paths remain relative to t
 Some tests also require their ABI is verified.  To indicate this the `validate_abi` field may be
 specified, as a boolean value.
 
-# FileCheck for 'fail' tests
+## FileCheck for 'fail' tests
 
 The tests in the `fail` category _must_ employ verification using pattern matching via the [FileCheck](https://docs.rs/filecheck/latest/filecheck/)
 crate.  The checker directives are specified in comments (lines beginning with `#`) in the `test.toml`
@@ -60,7 +60,8 @@ Typically this is as simple as just adding a `# check: ...` line to the line spe
 error or warning message expected from compiling the test.  `FileCheck` also has other directives for
 fancier pattern matching, as specified in the [FileCheck docs](https://docs.rs/filecheck/latest/filecheck/).
 
-**Note:** The output from the compiler is colorized, usually to red or yellow, and this involves
+> **Note**
+> The output from the compiler is colorized, usually to red or yellow, and this involves
 printing ANSI escape sequences to the terminal.  These sequences can confuse `FileCheck` as it tries
 to match patterns on 'word' boundaries.  The first word in an error message is most likely prefixed
 with an escape sequence and can cause the check to fail.
@@ -70,7 +71,7 @@ string' pattern `$()` to direct the matcher as to where the pattern starts.
 
 E.g, `# check: $()The name "S" shadows another symbol with the same name.`
 
-# Examples
+## Examples
 
 The following is a common example for tests in the `should_pass/language` directory.  The test
 should be compiled, run on the VM, should expect a return value of 42 and should also validate the

test/src/ir_generation/README.md

@@ -2,25 +2,26 @@
 
 These tests are for validating specific aspects of IR and ASM generation as opposed to full end-to-end testing.
 
-## How to author new tests.
+## How to author new tests
 
 To create a new test write a small snippet of Sway to target the specific IR or ASM construct. Placing this file under `ir_generation/tests` will automatically add it to the suite.
 
 The [FileCheck](https://docs.rs/filecheck/latest/filecheck/) crate is used to verify the output from the compiler.  If no `FileCheck` directives are found then the harness will print to screen the IR or ASM output which will be tested against, and the required directives can be based on that text.
 
+> **Note**
 > See the existing tests in the `ir_generation/tests` for examples.
 
-## Built in `regex` directives.
+## Built in `regex` directives
 
 Some commonly used `FileCheck` `regex` directives are provided by the harness for use in matching particular IR and ASM tokens:
 
 * `VAL` - matches `v\d+` which is the syntax for IR values.
-* `ID` - matches `[_[:alpha:]][_0-9[:alpha:]]*` which is an identifer such as an IR block or function name.
+* `ID` - matches `[_[:alpha:]][_0-9[:alpha:]]*` which is an identifier such as an IR block or function name.
 * `MD` - matches `!\\d+` which is an IR metadata index.
 
 These built in directives are already used extensively in the suite.
 
-## Delimiting markers.
+## Delimiting markers
 
 Both checks against IR and ASM may be provided in the same Sway test source file.  IR checks are mandatory and ASM checks are optional.