[v10.0.x] Enable doc-validator for specific directories (#68724)

* Enable doc-validator for specific directories (#63524)

* Enable doc-validator for specific directories

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix one linting error to trigger CI

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update doc-validator to latest release

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update make-docs procedure

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Use doc-validator version from CI in local make target

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Revert to 1.11.0

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* adds missing descriptions

* Fix titles and headings

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix link formats

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix easy to resolve anchors

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Remove broken anchor link

This anchor appears to have been broken for a long time.

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Use doc-validator image with support for numbered anchors

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update make-docs procedure to support doc-validator 2.0.x

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Fix a bunch of broken anchors

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Ignore old whatsnew content

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Update doc-validator to v2.0.x and use reviewdog to report errors

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* removes broken links

---------

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Chris Moyer <chris.moyer@grafana.com>
(cherry picked from commit 560f49b3dc)

* Fix doc-validator linting

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

---------

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

docs/docs.mk

@@ -1,3 +1,5 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# 2.0.0 (2023-05-18)
 include variables.mk
 -include variables.mk.local
 
@@ -52,6 +54,11 @@ ifeq ($(origin DOC_VALIDATOR_IMAGE), undefined)
 export DOC_VALIDATOR_IMAGE := grafana/doc-validator:latest
 endif
 
+# Container image used for vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
 # PATH-like list of directories within which to find projects.
 # If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
 ifeq ($(origin REPOS_PATH), undefined)
@@ -91,10 +98,10 @@ docs-no-pull: make-docs
 .PHONY: docs-debug
 docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
 docs-debug: make-docs
-	WEBSITE_EXEC='hugo server --debug' $(PWD)/make-docs $(PROJECTS)
+	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --debug' $(PWD)/make-docs $(PROJECTS)
 
 .PHONY: doc-validator
-doc-validator: ## Run docs-validator on the entire docs folder.
+doc-validator: ## Run doc-validator on the entire docs folder.
 doc-validator: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) $(PWD)/make-docs $(PROJECTS)
 
@@ -103,6 +110,11 @@ doc-validator/%: ## Run doc-validator on a specific path. To lint the path /docs
 doc-validator/%: make-docs
 	DOCS_IMAGE=$(DOC_VALIDATOR_IMAGE) DOC_VALIDATOR_INCLUDE=$(subst doc-validator/,,$@) $(PWD)/make-docs $(PROJECTS)
 
+.PHONY: vale
+vale: ## Run vale on the entire docs folder.
+vale: make-docs
+	DOCS_IMAGE=$(VALE_IMAGE) $(PWD)/make-docs $(PROJECTS)
+
 .PHONY: update
 update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
 	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk