diff --git a/.github/workflows/link-validation.yaml b/.github/workflows/link-validation.yaml
new file mode 100644
index 00000000000..484071b4cc2
--- /dev/null
+++ b/.github/workflows/link-validation.yaml
@@ -0,0 +1,61 @@
+name: Verifies documentation links
+
+on:
+ push:
+ branches:
+ - master
+ pull_request:
+ schedule:
+ - cron: "0 3 * * 1" # Every Monday at 03:00
+
+jobs:
+ verify-links:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ with:
+ fetch-depth: 1
+
+ - name: Install Taskfile
+ uses: Arduino/actions/setup-taskfile@master
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Install Go
+ uses: actions/setup-go@v2
+ with:
+ go-version: "1.14"
+
+ - name: Installs Go dependencies
+ shell: bash
+ run: go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+
+ - name: Install protoc compiler
+ uses: arduino/setup-protoc@v1.1.0
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Setup Python
+ uses: actions/setup-python@v1
+ with:
+ python-version: "3.6"
+ architecture: "x64"
+
+ - name: Cache dependencies
+ uses: actions/cache@v1
+ with:
+ path: ~/.cache/pip
+ key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+ restore-keys: |
+ ${{ runner.os }}-pip-
+
+ - name: Install Python dependencies
+ run: |
+ python3 -m pip install --upgrade pip
+ python3 -m pip install -r ./requirements_docs.txt
+
+ - name: Build docs
+ run: task docs:build
+
+ - name: Verify links
+ run: task docs:check-links
diff --git a/Taskfile.yml b/Taskfile.yml
index 35564237461..ac597457a89 100755
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -54,6 +54,18 @@ tasks:
cmds:
- npx {{ .PRETTIER }} --check "**/*.md"
+ docs:check-links:
+ desc: Verifies there are no dead links in documentation
+ cmds:
+ - |
+ npx -p markdown-link-check -c '
+ STATUS=0
+ for file in $(find -name "*.md"); do
+ markdown-link-check -c markdown-link-check-config.json -q "$file"
+ STATUS=$(( $STATUS + $? ))
+ done
+ exit $STATUS'
+
docs:format:
desc: Automatically formats documentation
cmds:
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index db098fca904..993f06a1453 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -218,8 +218,8 @@ If you don't see any error, hit http://127.0.0.1:8000 with your browser to navig
### Docs publishing
The present git repository has a special branch called `gh-pages` that contains the generated HTML code for the docs
-website; every time a change is pushed to this special branch, GitHub automatically triggers a [deployment][8] to pull
-the change and publish a new version of the website. Do not open Pull Requests to push changes to the `gh-pages` branch,
+website; every time a change is pushed to this special branch, GitHub automatically triggers a deployment to pull the
+change and publish a new version of the website. Do not open Pull Requests to push changes to the `gh-pages` branch,
that will be done exclusively from the CI.
### Docs versioning
@@ -342,7 +342,6 @@ If your PR doesn't need to be included in the changelog, please start the PR tit
[5]: https://github.com/ofek/hatch
[6]: https://github.com/protocolbuffers/protobuf/releases
[7]: https://pages.github.com/
-[8]: https://github.com/arduino/arduino-cli/deployments?environment=github-pages#activity-log
[9]: https://www.mkdocs.org/
[10]: https://github.com/jimporter/mike
[11]: https://github.com/arduino/arduino-cli/blob/master/.github/workflows/docs.yaml
diff --git a/docs/configuration.md b/docs/configuration.md
index aea470b5677..5e040e25dba 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -126,12 +126,12 @@ additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index
[grpc]: https://grpc.io
[sketchbook directory]: sketch-specification.md#sketchbook
-[arduino-cli config dump]: ../commands/arduino-cli_config_dump
-[arduino cli command reference]: ../commands/arduino-cli
-[arduino-cli global flags]: ../commands/arduino-cli_config/#options-inherited-from-parent-commands
+[arduino-cli config dump]: commands/arduino-cli_config_dump.md
+[arduino cli command reference]: commands/arduino-cli.md
+[arduino-cli global flags]: commands/arduino-cli_config.md#options-inherited-from-parent-commands
[export command]: https://ss64.com/bash/export.html
[set command]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1
-[arduino-cli config init]: ../commands/arduino-cli_config_init
+[arduino-cli config init]: commands/arduino-cli_config_init.md
[json]: https://www.json.org
[toml]: https://github.com/toml-lang/toml
[yaml]: https://en.wikipedia.org/wiki/YAML
diff --git a/docs/index.md b/docs/index.md
index d40820b0114..6d6f89954dd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,4 +17,4 @@ services and messages are detailed in the [gRPC reference] pages.
[installation]: installation.md
[getting started guide]: getting-started.md
[client_example]: https://github.com/arduino/arduino-cli/blob/master/client_example
-[grpc reference]: rpc/commands
+[grpc reference]: rpc/commands.md
diff --git a/docs/integration-options.md b/docs/integration-options.md
index 2675b59e38b..47be96ac40c 100644
--- a/docs/integration-options.md
+++ b/docs/integration-options.md
@@ -95,10 +95,10 @@ tracker] if you’ve got a use case that doesn’t fit one of the three pillars.
[configuration documentation]: configuration.md
[json]: https://www.json.org
[installation script]: installation.md#use-the-install-script
-[command reference]: ../commands/arduino-cli
+[command reference]: commands/arduino-cli.md
[grpc]: https://grpc.io/
[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
-[daemon mode]: ../commands/arduino-cli_daemon
+[daemon mode]: commands/arduino-cli_daemon.md
[grpc interface reference]: ../rpc/commands
[grpc supported languages]: https://grpc.io/docs/languages/
[arduino cli repository]: https://github.com/arduino/arduino-cli
diff --git a/docs/library-specification.md b/docs/library-specification.md
index 5331f64201a..269bba55475 100644
--- a/docs/library-specification.md
+++ b/docs/library-specification.md
@@ -9,7 +9,7 @@ This new library format is intended to be used in tandem with **Library Manager*
The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy
to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and
[Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11)
-as well as [`arduino-cli lib`](../commands/arduino-cli_lib).
+as well as [`arduino-cli lib`](commands/arduino-cli_lib.md).
More information about how Library Manager works is available
[here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
@@ -22,7 +22,7 @@ code to specific architectures.
## See also
- [Arduino library style guide](http://arduino.cc/en/Reference/APIStyleGuide)
-- [Library dependency resolution process documentation](../sketch-build-process/#dependency-resolution)
+- [Library dependency resolution process documentation](sketch-build-process.md#dependency-resolution)
## 1.5 library format (rev. 2.2)
@@ -70,7 +70,7 @@ otherwise below, **all fields are required**. The available fields are:
- **depends** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of
dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to
install the dependencies during installation of the library.
- [`arduino-cli lib install`](../commands/arduino-cli_lib_install) will automatically install the dependencies. Since
+ [`arduino-cli lib install`](commands/arduino-cli_lib_install.md) will automatically install the dependencies. Since
spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the
name without ambiguity for example:
`depends=Very long library name, Another library with long-name`
- **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to
diff --git a/docs/platform-specification.md b/docs/platform-specification.md
index c80cfccac07..2e283e0b2a0 100644
--- a/docs/platform-specification.md
+++ b/docs/platform-specification.md
@@ -116,7 +116,7 @@ The following meta-data must be defined:
version=1.5.3
The **name** will be shown as the Arduino IDE's Board menu section title or the Name field of
-[`arduino-cli core list`](../commands/arduino-cli_core_list)'s output for the platform.
The **version** is currently
+[`arduino-cli core list`](commands/arduino-cli_core_list.md)'s output for the platform.
The **version** is currently
unused, it is reserved for future use (probably together with the Boards Manager to handle dependencies on cores).
### Build process
@@ -592,7 +592,7 @@ If the user didn't enable verbose mode, then **{upload.params.quiet}** is used i
### Sketch upload configuration
The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses
-[`arduino-cli upload`](../commands/arduino-cli_upload). Arduino uses the term "upload" for the process of transferring a
+[`arduino-cli upload`](commands/arduino-cli_upload.md). Arduino uses the term "upload" for the process of transferring a
program to the Arduino board. The **upload.tool** property determines the tool to be used for upload. A specific
**upload.tool** property should be defined for every board in boards.txt:
@@ -685,7 +685,7 @@ support uploading via programmer.
### Serial port
The full path (e.g., `/dev/ttyACM0`) of the port selected via the IDE or
-[`arduino-cli upload`](../commands/arduino-cli_upload)'s `--port` option is available as a configuration property
+[`arduino-cli upload`](commands/arduino-cli_upload.md)'s `--port` option is available as a configuration property
**{serial.port}**.
The file component of the port's path (e.g., `ttyACM0`) is available as the configuration property
diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md
index 5186d4ccb9e..9d59f64f36a 100644
--- a/docs/sketch-build-process.md
+++ b/docs/sketch-build-process.md
@@ -103,7 +103,7 @@ The "folder name priority" is determined as follows (in order of highest to lowe
The "location priority" is determined as follows (in order of highest to lowest priority):
1. The library is in a custom libraries path specified via the
- [`--libraries` option](../commands/arduino-cli_compile/#options) of `arduino-cli compile` (in decreasing order of
+ [`--libraries` option](commands/arduino-cli_compile.md#options) of `arduino-cli compile` (in decreasing order of
priority when multiple custom paths are defined)
1. The library is in the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory
1. The library is bundled with the board platform/core
diff --git a/docs/sketch-specification.md b/docs/sketch-specification.md
index a126a89c9ed..d5a2f05dd54 100644
--- a/docs/sketch-specification.md
+++ b/docs/sketch-specification.md
@@ -66,9 +66,9 @@ Arduino CLI and Arduino Web Editor use a file named sketch.json, located in the
metadata.
The `cpu` key contains the board configuration information. This can be set via
-[`arduino-cli board attach`](../commands/arduino-cli_board_attach/) or by selecting a board in the Arduino Web Editor
+[`arduino-cli board attach`](commands/arduino-cli_board_attach.md) or by selecting a board in the Arduino Web Editor
while the sketch is open. With this configuration set, it is not necessary to specify the `--fqbn` or `--port` flags to
-the [`arduino-cli compile`](../commands/arduino-cli_compile/) or [`arduino-cli upload`](../commands/arduino-cli_upload/)
+the [`arduino-cli compile`](commands/arduino-cli_compile.md) or [`arduino-cli upload`](commands/arduino-cli_upload.md)
commands when compiling or uploading the sketch.
The `included_libs` key defines the library versions the Arduino Web Editor uses when the sketch is compiled. This is
diff --git a/markdown-link-check-config.json b/markdown-link-check-config.json
new file mode 100644
index 00000000000..0ec33e8541f
--- /dev/null
+++ b/markdown-link-check-config.json
@@ -0,0 +1,10 @@
+{
+ "ignorePatterns": [
+ {
+ "pattern": "https?://localhost:\\d*/"
+ },
+ {
+ "pattern": "https?://(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?):\\d*"
+ }
+ ]
+}