diff --git a/Earthfile b/Earthfile index 2d5ad566e..681554ef3 100644 --- a/Earthfile +++ b/Earthfile @@ -4,14 +4,18 @@ FROM debian:stable-slim # cspell: words livedocs sitedocs +# Check Markdown in this repo. markdown-check: - # Check Markdown in this repo. LOCALLY DO ./earthly/mdlint+MDLINT_LOCALLY --src=$(echo ${PWD}) +# check-markdown can be done remotely. +check-markdown: + DO ./earthly/mdlint+CHECK + +# markdown-check-fix perform markdown check with fix in this repo. markdown-check-fix: - # Check Markdown in this repo. LOCALLY DO ./earthly/mdlint+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix @@ -22,6 +26,16 @@ spell-check: DO ./earthly/cspell+CSPELL_LOCALLY --src=$(echo ${PWD}) +## ----------------------------------------------------------------------------- +## +## Standard CI targets. +## +## These targets are discovered and executed automatically by CI. + +# check - run all checks. +check: + BUILD +check-markdown + repo-docs: # Create artifacts of extra files we embed inside the documentation when its built. FROM scratch diff --git a/docs/src/appendix/important/coc.md b/docs/src/appendix/important/coc.md index 20f130259..0880bb055 100644 --- a/docs/src/appendix/important/coc.md +++ b/docs/src/appendix/important/coc.md @@ -2,7 +2,6 @@ icon: material/file-sign title: Code of Conduct --- - - + {{ include_file('includes/repo/CODE_OF_CONDUCT.md') }} diff --git a/docs/src/appendix/important/contributing.md b/docs/src/appendix/important/contributing.md index fcce80fe5..2d8933985 100644 --- a/docs/src/appendix/important/contributing.md +++ b/docs/src/appendix/important/contributing.md @@ -3,5 +3,5 @@ icon: material/pen-plus --- - + {{ include_file('includes/repo/CONTRIBUTING.md') }} diff --git a/docs/src/appendix/important/security.md b/docs/src/appendix/important/security.md index fd86f01d6..a33b9b349 100644 --- a/docs/src/appendix/important/security.md +++ b/docs/src/appendix/important/security.md @@ -3,5 +3,5 @@ icon: material/security --- - + {{ include_file('includes/repo/SECURITY.md') }} diff --git a/docs/src/guides/markdown.md b/docs/src/guides/markdown.md new file mode 100644 index 000000000..148f33b35 --- /dev/null +++ b/docs/src/guides/markdown.md @@ -0,0 +1,108 @@ +--- +icon: simple/markdown +--- + +# Markdown Check + +This Earthly Target and UDC enables uniform linting of Markdown files to maintain consistency and quality. + +This UDC is **NOT** intended to be used inside container builds. +Its sole purpose is to enforce uniform style rules for all markdown files in a repository. +It makes no assumptions about which files may or may not end up inside a container or are part of a build. +This is *INTENTIONAL*. + +IF this UDC is used inside a container build, it is **NOT** a bug if it does not do the correct thing. + +## Introduction + +Markdown file checking is integrated into the `check` pipeline. +The reference to the pipeline can be found [here](https://input-output-hk.github.io/catalyst-ci/onboarding/). +The goal of the `check` stage is to ensure the overall health of the project. +Specifically, for markdown checks, it ensures that all markdown files follow valid rules. + +## Configuration + +Each repo will need two configuration files in the root of the repository: + +* `.markdownlint.jsonc` - Configures individual markdown rules. +* `.markdownlint-cli2.jsonc` - Configures the CLI Tool. + +The configuration should be copied from the root of the Catalyst-CI repository into the target repo. +Individual projects should have no need to individually customize these rules. +Any changes to the markdown rules should be it's own PR. +It should first be made to the Base rules in the Catalyst-CI project and only once merged, copied into all other effected repos. + +This is to ensure a consistent rule set across all repos. + +Additional references to the rules can be read [here](https://github.com/DavidAnson/markdownlint/) + +## How it works + +Linting is performed with the [`mdlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) program. + +This linter is to be used in preference to any other Markdown linter. +This is because we need to provide uniform and consistent Markdown formatting and linting across the project and between projects. + +## Using the markdown check + +### Locally + +#### Running check + +Executing `earthly +check` will automatically run all checks, including the verification of markdown files in the repository. +To view the specific checks performed during the `check` stage, use the command `earthly doc`. +All the check done in check target should be named as `check-`. + +#### Running markdown fix + +If an error occurs, `earthly +markdown-check-fix` can be used to automatically fix the error. + +!!! Note + Please note that this command will fix the issues based on the capabilities of the linter. + + +### Remotely + +Performing a markdown check can be done in your repository by adding the following code: + +#### Checking the markdown in your repo + +```earthfile +check-markdown: + DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:+CHECK +``` + +Note that the source directory is not required since default is set as current directory. + +#### Checking and fixing the markdown in your repo + +```earthfile +markdown-check-fix: + LOCALLY + + DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix +``` + +In this use case, the UDC is run Locally, so that the markdown in the repo can be directly checked. + + +!!! Note + `tag` is needed to be specified to the right version. + + +## Disable markdownlint rules + +Markdown linter rules can be disable for specific file or lines. + +``` html + +``` + +For more example, please refer to this [doc](https://github.com/DavidAnson/markdownlint/#configuration) + +## Editor Integration + +mdlint-cli2 is integrated into VSCode and may be integrated into other Editors. + +The editor integration should pick up both the `.markdownlint.jsonc` and `.markdownlint-cli2.jsonc` configuration files. +It will then behave exactly the same as the Earthly UDC. diff --git a/earthly/mdlint/Earthfile b/earthly/mdlint/Earthfile index 1fad10b3c..2e18dd2a9 100644 --- a/earthly/mdlint/Earthfile +++ b/earthly/mdlint/Earthfile @@ -34,11 +34,46 @@ MDLINT_LOCALLY: RUN docker run \ --rm \ -v $src:/workdir \ - davidanson/markdownlint-cli2-rules:v0.10.0 \ + davidanson/markdownlint-cli2-rules:v0.11.0 \ "**/*.md" \ --config $cfg_file \ $fix +# Markdown check used in standard CI target check. +CHECK: + # DO NOT RUN THIS UDC INSIDE CONTAINER BUILDS. + # IT IS NOT FOR CONTAINER BUILDS. + # See: https://github.com/earthly/earthly/issues/580 + + # Linting is done with MarkdownLint CLI2 + # See: https://github.com/DavidAnson/markdownlint-cli2 + # We use a special container which includes all rule extensions to markdownlint + # Notably, we rely on the `max-one-sentence-per-line` rule which helps keep + # diffs of markdown files small and legible. This rule is only currently + # in the `next` branch of `markdownlint`. + # Container is built by: + # https://github.com/DavidAnson/markdownlint-cli2/blob/next/docker/Dockerfile-rules + COMMAND + + ARG src = . + + # Unlikely this ever needs to be changed. + ARG cfg_file=.markdownlint-cli2.jsonc + + FROM davidanson/markdownlint-cli2-rules:v0.11.0 + + # Status line for what we are about to do. + RUN echo Linting Markdown Recursively from: $src + + # Run the linter with the given arguments, and recursively check all markdown files. + # The directory to be checked `MUST` have a `.markdownlint-sli2.jsonc` file. + # cspell: words davidanson + WORKDIR /work + COPY $src . + RUN markdownlint-cli2 \ + "**/*.md" \ + --config $cfg_file + # A Test and example invocation of the above UDC. mdlint-test: # Test Markdown lint checks. diff --git a/earthly/mdlint/Readme.md b/earthly/mdlint/Readme.md index e37745748..8efb3486b 100644 --- a/earthly/mdlint/Readme.md +++ b/earthly/mdlint/Readme.md @@ -1,62 +1,3 @@ # Markdown Linter -This Earthly Target and UDC enables uniform linting of Markdown files to maintain consistency and quality. - -## DO NOT RUN AS PART OF A CONTAINER BUILD TARGET - -This UDC is **NOT** intended to be used inside container builds. -Its sole purpose is to enforce uniform style rules for all markdown files in a repository. -It makes no assumptions about which files may or may not end up inside a container or are part of a build. -This is *INTENTIONAL*. - -IF this UDC is used inside a container build, it is **NOT** a bug if it does not do the correct thing. - -## How it works - -Linting is performed with the [`mdlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) program. - -Use the `MDLINT` Earthly UDC to enable uniform and consistent Markdown Format checking. - -This linter is to be used in preference to any other Markdown linter. -This is because we need to provide uniform and consistent Markdown formatting and linting across the project and between projects. - -## Invocation - -In an Earthfile in your repo, add the following: - -```earthfile -markdown-lint: - # Check Markdown in this repo. - LOCALLY - - DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v1.2.0+MDLINT_LOCALLY --src=$(echo ${PWD}) - -markdown-lint-fix: - # Check Markdown in this repo. - LOCALLY - - DO github.com/input-output-hk/catalyst-ci/earthly/mdlint:v1.2.0+MDLINT_LOCALLY --src=$(echo ${PWD}) --fix=--fix -``` - -In this use case, the UDC is run Locally, so that the markdown in the repo can be directly checked. - -## Configuration - -Each repo will need two configuration files in the root of the repository: - -* `.markdownlint.jsonc` - Configures individual markdown rules. -* `.markdownlint-cli2.jsonc` - Configures the CLI Tool. - -The configuration should be copied from the root of the Catalyst-CI repository into the target repo. -Individual projects should have no need to individually customize these rules. -Any changes to the markdown rules should be it's own PR. -It should first be made to the Base rules in the Catalyst-CI project and only once merged, copied into all other effected repos. - -This is to ensure a consistent rule set across all repos. - -## Editor Integration - -mdlint-cli2 is integrated into VSCode and may be integrated into other Editors. - -The editor integration should pick up both the `.markdownlint.jsonc` and `.markdownlint-cli2.jsonc` configuration files. -It will then behave exactly the same as the Earthly UDC. +See [link](/docs/src/guides/markdown.md) for the references.