feat: add markdown check in check target (#119)

* feat: implement markdown check in check target

* feat: add check-markdown-fix to check target

* chore: add and fix comment

* fix: remove markdown fix in check

* chore: fix comment

* fix: markdownlint-disable name for require-headings

* fix: check-markdown, add check function, and update markdownlint-cli2-rules to v0.11.0

* chore: fix and add comment

* chore: add readme for markdown check

* chore: change icon

* chore: fix readme

* chore: fix comment

* chore: combine markdown check and markdown lint docs

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

docs/src/appendix/important/coc.md

@@ -2,7 +2,6 @@
 icon: material/file-sign
 title: Code of Conduct
 ---
-
 <!-- markdownlint-disable first-line-h1 -->
-<!-- markdownlint-disable required-headers -->
+<!-- markdownlint-disable required-headings -->
 {{ include_file('includes/repo/CODE_OF_CONDUCT.md') }}

docs/src/appendix/important/contributing.md

@@ -3,5 +3,5 @@ icon: material/pen-plus
 ---
 
 <!-- markdownlint-disable first-line-h1 -->
-<!-- markdownlint-disable required-headers -->
+<!-- markdownlint-disable required-headings -->
 {{ include_file('includes/repo/CONTRIBUTING.md') }}

docs/src/appendix/important/security.md

@@ -3,5 +3,5 @@ icon: material/security
 ---
 
 <!-- markdownlint-disable first-line-h1 -->
-<!-- markdownlint-disable required-headers -->
+<!-- markdownlint-disable required-headings -->
 {{ include_file('includes/repo/SECURITY.md') }}

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-<name>`.
+
+#### Running markdown fix
+
+If an error occurs, `earthly +markdown-check-fix` can be used to automatically fix the error.
+<!-- markdownlint-disable max-one-sentence-per-line -->
+!!! Note
+    Please note that this command will fix the issues based on the capabilities of the linter.
+<!-- markdownlint-enable max-one-sentence-per-line -->
+
+### 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:<tag>+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:<tag>+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.
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+!!! Note
+    `tag` is needed to be specified to the right version.
+<!-- markdownlint-enable max-one-sentence-per-line -->
+
+## Disable markdownlint rules
+
+Markdown linter rules can be disable for specific file or lines.
+
+``` html
+<!-- markdownlint-disable rules -->
+```
+
+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.

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.

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.