Merge pull request #3885 from tarlepp/chore(ops)/markdown-linter

Chore(ops) - Markdown linter improvements

Author: tarlepp

.github/workflows/main.yml

@@ -53,14 +53,11 @@ jobs:
     steps:
       - *checkout_step
 
-      - name: Lint all markdown documentation files
-        uses: DavidAnson/markdownlint-cli2-action@ded1f9488f68a970bc66ea5619e13e9b52e601cd # v23.2.0
-        with:
-          globs: |
-            README.md
-            CLAUDE.md
-            doc/*.md
-            .github/*.md
+      - name: Setup Node + Corepack + Yarn deps
+        uses: ./.github/actions/setup-yarn
+
+      - name: Run `yarn lint:md`
+        run: yarn lint:md
 
   check-translations:
     name: Check that translations are up-to-date

Makefile

@@ -105,10 +105,11 @@ else
 	$(WARNING_DOCKER)
 endif
 
-lint: ## Lint TypeScript and SCSS files
+lint: ## Lint TypeScript, SCSS, and Markdown files
 ifeq ($(INSIDE_DOCKER), 1)
 	@make lint-ts
 	@make lint-scss
+	@make lint-md
 else ifeq ($(strip $(IS_RUNNING)),)
 	$(WARNING_DOCKER)
 else
@@ -138,10 +139,22 @@ else
 	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make lint-scss
 endif
 
-fix: ## Fix TypeScript and SCSS files
+lint-md: ## Lint Markdown files
+ifeq ($(INSIDE_DOCKER), 1)
+	@echo "\033[32mLinting Markdown files\033[39m"
+	@yarn run lint:md
+else ifeq ($(strip $(IS_RUNNING)),)
+	$(WARNING_DOCKER)
+else
+	$(NOTICE_HOST)
+	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make lint-md
+endif
+
+fix: ## Fix TypeScript, SCSS, and Markdown files
 ifeq ($(INSIDE_DOCKER), 1)
 	@make fix-ts
 	@make fix-scss
+	@make fix-md
 else ifeq ($(strip $(IS_RUNNING)),)
 	$(WARNING_DOCKER)
 else
@@ -171,6 +184,17 @@ else
 	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make fix-scss
 endif
 
+fix-md: ## Fix Markdown files
+ifeq ($(INSIDE_DOCKER), 1)
+	@echo "\033[32mFixing Markdown files\033[39m"
+	@yarn run fix:md
+else ifeq ($(strip $(IS_RUNNING)),)
+	$(WARNING_DOCKER)
+else
+	$(NOTICE_HOST)
+	@HOST_UID=$(HOST_UID) HOST_GID=$(HOST_GID) docker compose exec node make fix-md
+endif
+
 extract-translations: ## Extract translations from TypeScript and HTML template files
 ifeq ($(INSIDE_DOCKER), 1)
 	@echo "\033[32mExtracting translations\033[39m"

doc/COMMANDS.md

@@ -46,6 +46,8 @@ make start               # Start application in development mode
 make start-immutable     # Start development mode with `yarn install --immutable` in container entrypoint
 make start-build         # Start application in development mode and rebuild container
 make start-production    # Start application with the local production Angular configuration
+make start-yarn          # Run `yarn start` inside the running container
+make start-yarn-prod     # Run `yarn start-prod` inside the running container
 make stop                # Stop application containers
 ```
 
@@ -59,12 +61,14 @@ make fish               # Open a fish shell inside the node container
 ### Linting and fixing
 
 ```bash
-make lint               # Run TypeScript and SCSS linting
+make lint               # Run TypeScript, SCSS, and Markdown linting
 make lint-ts            # Run Angular/TypeScript linting
 make lint-scss          # Run SCSS linting with stylelint
-make fix                # Run TypeScript and SCSS auto-fixes
+make lint-md            # Run markdownlint for all tracked Markdown files
+make fix                # Run TypeScript, SCSS, and Markdown auto-fixes
 make fix-ts             # Run Angular/TypeScript lint fixes
 make fix-scss           # Run SCSS auto-fixes with stylelint
+make fix-md             # Run markdownlint auto fixes for tracked Markdown files
 ```
 
 ### Translations
@@ -114,8 +118,10 @@ yarn build-prod           # Create a production build
 yarn test                 # Run unit tests
 yarn lint:ts              # Run Angular/TypeScript linting
 yarn lint:scss            # Run stylelint for SCSS files
+yarn lint:md              # Run markdownlint for all tracked Markdown files
 yarn fix:ts               # Auto-fix Angular/TypeScript lint issues
 yarn fix:scss             # Auto-fix SCSS lint issues
+yarn fix:md               # Auto-fix markdownlint issues in tracked Markdown files
 yarn extract-translations # Extract translation keys
 yarn check-translations   # Validate translation files
 yarn i18n:extract         # Run Transloco key extraction

package.json

@@ -23,8 +23,10 @@
     "test": "ng test",
     "lint:ts": "ng lint",
     "lint:scss": "npx stylelint '**/*.scss'",
+    "lint:md": "git ls-files '*.[mM][dD]' | xargs -r npx markdownlint-cli2",
     "fix:ts": "ng lint --fix",
     "fix:scss": "npx stylelint --fix '**/*.scss'",
+    "fix:md": "git ls-files '*.[mM][dD]' | xargs -r npx markdownlint-cli2 --fix",
     "e2e": "ng e2e",
     "extract-translations": "transloco-keys-manager extract --sort --unflat --remove-extra-keys --emit-error-on-extra-keys --default-value=null && node -e \"const fs=require('fs');for(const file of fs.readdirSync('src/assets/i18n').filter((name)=>name.endsWith('.json'))){fs.appendFileSync('src/assets/i18n/'+file,'\\n');}\"",
     "check-translations": "sed -i 's/_/__/g; s/: null/x_x/g; s/: \"--- MISSING TRANSLATION ---\"/: null/g; s/x_x/: \"--- MISSING TRANSLATION ---\"/g; s/__/_/g' ./src/assets/i18n/*.json && git diff --exit-code ./src/assets/i18n/*.json",

scripts/README.md

@@ -27,7 +27,8 @@ File: `scripts/project-stats.sh`
 make project-stats
 ```
 
-If you are already inside the container, you can still run `bash scripts/project-stats.sh` directly.
+If you are already inside the container, you can still run
+`bash scripts/project-stats.sh` directly.
 
 ### GitHub Actions update checker
 
@@ -37,7 +38,8 @@ File: `scripts/check-action-updates.sh`
 make check-action-updates
 ```
 
-If you are already inside the container, you can still run `bash scripts/check-action-updates.sh` directly.
+If you are already inside the container, you can still run
+`bash scripts/check-action-updates.sh` directly.
 
 Print current pins as markdown:
 
@@ -46,9 +48,10 @@ bash scripts/check-action-updates.sh --current-pins-md
 ```
 
 Exit codes:
-- `0` = no discovery issues and no updates found
-- `1` = updates available
-- `2` = discovery issues found (for example unpinned refs or conflicting versions)
+
+* `0` = no discovery issues and no updates found
+* `1` = updates available
+* `2` = discovery issues found (for example unpinned refs or conflicting versions)
 
 ---