test(docs): add markdownlint and mkdocs CI checks #1556
Conversation
jnussbaum
changed the title
| .PHONY: docs-publish | ||
| docs-publish: ## build and publish docs to github Pages | ||
| mkdocs gh-deploy | ||
|
|
There was a problem hiding this comment.
We don't publish the docs of DSP-APP separately any more. So this command isn't used any more.
| .PHONY: docs-build | ||
| docs-build: ## build docs into the local 'site' folder | ||
| mkdocs build | ||
| mkdocs build --strict |
There was a problem hiding this comment.
The --strict flag is necessary, so that warnings are not silently ignored. Often, those warnings later create problems when I want to publish the docs to docs.dasch.swiss. So it is better to catch them early, and let the CI fail if problematic markdown files are checked in.
| .PHONY: docs-lint | ||
| docs-lint: ## runs the markdownlint linter on the docs | ||
| docker run -v $$(pwd):/workdir ghcr.io/igorshubovych/markdownlint-cli:latest --config .markdownlint.json -i docs/contribution/release-notes.md -i docs/index.md --disable MD033 -- "docs/**/*.md" | ||
|
|
There was a problem hiding this comment.
This runs markdownlint, which check the markdownfiles for syntax errors. These syntax errors sometimes break the layout on docs.dasch.swiss. So it's better to catch them early, and prevent checking in malformed files.
docs/user-guide/publication.md
Outdated
There was a problem hiding this comment.
This file is empty, and is not referenced in the documentation. So it doesn't make sense to leave it here.
| @@ -2,7 +2,7 @@ | |||
|
|
|||
| ## Your user profile and projects | |||
|
|
|||
| To change your personal information as well as your default language used by the interface, you can edit your profile by clicking *Edit my profile*. Currently, the avatar image comes from gravatar.com (go on their <a href="http://en.gravatar.com/" target="_blank">website</a> to register if you want your customized user photo). | |||
| To change your personal information as well as your default language used by the interface, you can edit your profile by clicking *Edit my profile*. Currently, the avatar image comes from gravatar.com (go on their [website](http://en.gravatar.com/) to register if you want your customized user photo). | |||
There was a problem hiding this comment.
markdown-style links are preferred over HTML-syntax
check every PR if the docs comply with mkdocs and markdownlint