Skip to content

Commit

Permalink
feat: add markdown check in check target (#119)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
bkioshn authored Dec 6, 2023
1 parent ead76a1 commit 0f8cc0a
Show file tree
Hide file tree
Showing 7 changed files with 164 additions and 67 deletions.
18 changes: 16 additions & 2 deletions Earthfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
3 changes: 1 addition & 2 deletions docs/src/appendix/important/coc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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') }}
2 changes: 1 addition & 1 deletion docs/src/appendix/important/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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') }}
2 changes: 1 addition & 1 deletion docs/src/appendix/important/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -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') }}
108 changes: 108 additions & 0 deletions docs/src/guides/markdown.md
Original file line number Diff line number Diff line change
@@ -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.
37 changes: 36 additions & 1 deletion earthly/mdlint/Earthfile
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
61 changes: 1 addition & 60 deletions earthly/mdlint/Readme.md
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 0f8cc0a

Please sign in to comment.