feat: markdownlint: Add a links checker and fix some links

.lycheeignore

@@ -0,0 +1,3 @@
+# list URLs that should be excluded for lychee link checher
+https://roidelapluie.be
+https://github.com/purpleidea/mgmt/commit

docs/development.md

@@ -16,7 +16,7 @@ be working properly.
 
 ## Using Docker
 
-Alternatively, you can check out the [docker-guide](docker-guide.md) in order to
+Alternatively, you can check out the [docker folder](../docker/) in order to
 develop or deploy using docker. This method is not endorsed or supported, so use
 at your own risk, as it might not be working properly.
 

docs/documentation.md

@@ -437,7 +437,7 @@ directory in the git source repository. It is available from:
 
 ### Systemd:
 
-See [`misc/mgmt.service`](misc/mgmt.service) for a sample systemd unit file.
+See [`misc/mgmt.service`](../misc/mgmt.service) for a sample systemd unit file.
 This unit file is part of the RPM.
 
 To specify your custom options for `mgmt` on a systemd distro:

docs/language-guide.md

@@ -591,7 +591,7 @@ Lexing is done using [nex](https://github.com/blynn/nex). It is a pure-golang
 implementation which is similar to _Lex_ or _Flex_, but which produces golang
 code instead of C. It integrates reasonably well with golang's _yacc_ which is
 used for parsing. The token definitions are in:
-[lang/lexer.nex](https://github.com/purpleidea/mgmt/tree/master/lang/lexer.nex).
+[lang/lexer.nex](https://github.com/purpleidea/mgmt/tree/master/lang/parser/lexer.nex).
 Lexing and parsing run together by calling the `LexParse` method.
 
 #### Parsing
@@ -603,7 +603,7 @@ and trial and error. One small advantage yacc has over standard yacc is that it
 can produce error messages from examples. The best documentation is to examine
 the source. There is a short write up available [here](https://research.swtch.com/yyerror).
 The yacc file exists at:
-[lang/parser.y](https://github.com/purpleidea/mgmt/tree/master/lang/parser.y).
+[lang/parser.y](https://github.com/purpleidea/mgmt/tree/master/lang/parser/parser.y).
 Lexing and parsing run together by calling the `LexParse` method.
 
 #### Interpolation

docs/puppet-guide.md

@@ -69,7 +69,7 @@ be avoided.
 ### Unsupported resources
 
 Puppet has a fairly large number of
-[built-in types](https://docs.puppet.com/puppet/latest/reference/type.html),
+[built-in types](https://www.puppet.com/docs/puppet/8/cheatsheet_core_types.html),
 and countless more are available through
 [modules](https://forge.puppet.com/). It's unlikely that all of them will
 eventually receive native counterparts in `mgmt`.
@@ -115,7 +115,7 @@ puppet mgmtgraph print --code 'file { "/tmp/mgmt-test": backup => false }'
 ```
 
 This is tedious in a more complex manifest. A good simplification is the
-following [resource default](https://docs.puppet.com/puppet/latest/reference/lang_defaults.html)
+following [resource default](https://www.puppet.com/docs/puppet/8/lang_defaults)
 anywhere on the top scope of your manifest:
 
 ```puppet

docs/resource-guide.md

@@ -716,7 +716,7 @@ Higher level resource collections will be possible once the `mgmt` DSL is ready.
 ### Why does the resource API have `CheckApply` instead of two separate methods?
 
 In an early version we actually had both "parts" as separate methods, namely:
-`StateOK` (Check) and `Apply`, but the [decision](58f41eddd9c06b183f889f15d7c97af81b0331cc)
+`StateOK` (Check) and `Apply`, but the [decision](https://github.com/purpleidea/mgmt/commit/58f41eddd9c06b183f889f15d7c97af81b0331cc)
 was made to merge the two into a single method. There are two reasons for this:
 
 1. Many situations would involve the engine running both `Check` and `Apply`. If

misc/make-deps.sh

@@ -168,6 +168,15 @@ fold_end "Install golang tools"
 fold_start "Install miscellaneous tools"
 command -v mdl &>/dev/null || gem install mdl --no-document || true	# for linting markdown files
 command -v fpm &>/dev/null || gem install fpm --no-document || true	# for cross distro packaging
+# for checking links
+LYCHEE=$(command -v lychee 2>/dev/null) || true
+if [ -z "$LYCHEE" ]; then
+	LYCHEE_VERSION='v0.15.1'	# current stable version
+	LYCHEE_TMP='/tmp/'
+	LYCHEE_FILE="${LYCHEE_TMP}lychee-${LYCHEE_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
+	wget "https://github.com/lycheeverse/lychee/releases/download/${LYCHEE_VERSION}/lychee-${LYCHEE_VERSION}-x86_64-unknown-linux-gnu.tar.gz" -O "$LYCHEE_FILE"
+	tar -C /usr/local/bin -xzvf "$LYCHEE_FILE"
+fi
 fold_end "Install miscellaneous tools"
 
 cd "$XPWD" >/dev/null

test/test-markdownlint.sh

@@ -42,6 +42,13 @@ EOF
 
 #STYLE="test/mdl.style"	# style file
 
+LYCHEE=$(command -v lychee 2>/dev/null) || true
+if [ -z "$LYCHEE" ]; then
+	fail_test "The 'lychee' utility can't be found.
+	Installation guide:
+	https://github.com/lycheeverse/lychee/blob/master/README.md#installation"
+fi
+
 find_files() {
 	git ls-files | grep '\.md$'
 }
@@ -64,6 +71,12 @@ bad_files=$(
 		if ! "$MDL" --style "$STYLE" "$i" 1>&2; then
 			echo "$i"
 		fi
+
+		# check links in docs
+		# if file is from the directory docs/ then check links
+		if [[ "$i" == docs/* ]] && ! "$LYCHEE" -n "$i" 1>&2; then
+			echo "$i"
+		fi
 	done
 )