Lint markdown files

.github/workflows/build.yml

@@ -0,0 +1,26 @@
+name: Build
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: exercises
+
+jobs:
+  build:
+    name: Check if tests compile cleanly with starter sources
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - name: Set up JDK 1.17
+        uses: actions/setup-java@0ab4596768b603586c0de567f2430c30f5b0d2b0
+        with:
+          java-version: 17
+          distribution: "temurin"
+      - name: Check if tests compile cleanly with starter sources
+        run: ./gradlew compileStarterTestJava --continue

.github/workflows/gradle.yml → .github/workflows/lint.yml

@@ -1,4 +1,4 @@
-name: Gradle
+name: Lint
 
 on:
   pull_request:
@@ -7,12 +7,12 @@ on:
       - main
   workflow_dispatch:
 
-defaults:
-  run:
-    working-directory: exercises
+permissions:
+  contents: read
 
 jobs:
-  build:
+  java:
+    name: Lint Java files using Checkstyle
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
@@ -21,17 +21,14 @@ jobs:
         with:
           java-version: 17
           distribution: "temurin"
-      - name: Check if tests compile cleanly with starter sources
-        run: ./gradlew compileStarterTestJava --continue
+      - name: Run checkstyle
+        run: ./gradlew check --exclude-task test --continue
+        working-directory: exercises
 
-  lint:
+  markdown:
+    name: Lint Markdown files
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
-      - name: Set up JDK 1.17
-        uses: actions/setup-java@0ab4596768b603586c0de567f2430c30f5b0d2b0
-        with:
-          java-version: 17
-          distribution: "temurin"
-      - name: Run checkstyle
-        run: ./gradlew check --exclude-task test --continue
+      - name: Lint markdown
+        uses: DavidAnson/markdownlint-cli2-action@ed4dec634fd2ef689c7061d5647371d8248064f1

.github/workflows/test.yml

@@ -9,6 +9,7 @@ on:
 
 jobs:
   test:
+    name: Test all exercises using java-test-runner
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11

.markdownlint-cli2.jsonc

@@ -0,0 +1,21 @@
+{
+  "globs": [
+    "concepts/**/*.md",
+    "docs/**/*.md",
+    "exercises/**/*.md",
+    "reference/**/*.md",
+    "*.md"
+  ],
+  "ignores": [
+    // Deprecated exercises should never be updated
+    "exercises/concept/blackjack/**/*.md",
+    "exercises/practice/accumulate/**/*.md",
+    "exercises/practice/beer-song/**/*.md",
+    "exercises/practice/binary/**/*.md",
+    "exercises/practice/diffie-hellman/**/*.md",
+    "exercises/practice/hexadecimal/**/*.md",
+    "exercises/practice/octal/**/*.md",
+    "exercises/practice/strain/**/*.md",
+    "exercises/practice/trinary/**/*.md"
+  ]
+}

.markdownlint.jsonc

@@ -0,0 +1,14 @@
+// Configuration is based on the Exercism Markdown specification, see:
+// https://exercism.org/docs/building/markdown/markdown
+//
+// For information on writing markdownlint configuration see:
+// https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig
+{
+  "MD004": {
+    "style": "dash" // Prefer hyphens for unordered lists
+  },
+  "MD013": false, // Exercism tends to break lines at sentence ends rather than at a column limit
+  "MD024": false, // The format for instructions.md requires  repeated headings, e.g. "Task"
+  "MD033": false, // Inline HTML is allowed when used sparingly
+  "MD048": false // We want three backticks for codeblocks, but four tildes for special blocks.
+}

CONTRIBUTING.md

@@ -102,9 +102,15 @@ gradle compileStarterTestJava
 When you finished your changes and checked that all validations have passed, it's time to commit and push them to your fork:
 
 ```sh
-$ git add .
-$ git commit -m "(An intention-revealing commit message)"
-$ git push -u origin your-branch-name
+git add .
+```
+
+```sh
+git commit -m "(An intention-revealing commit message)"
+```
+
+```sh
+git push -u origin your-branch-name
 ```
 
 Then, open a Pull Request on the [exercism/java][track-repo] repository.

POLICIES.md

@@ -121,7 +121,7 @@ References: [[1](https://github.com/exercism/java/issues/395#issue-215734887)]
 ### Name test class after class under test
 
 > If you're testing a class called `SomeClassName` then your test class should be called `SomeClassNameTest`.
-
+>
 > The exception to this is if the tests are split into several test classes where each test class tests different functionality. In that case each class should be named `SomeClassNameFunctionalityTest` where `Functionality` is the name of the functionality to be tested in that class. See the [clock exercise](https://github.com/exercism/java/tree/main/exercises/practice/clock) as an example.
 
 References: [[1](https://github.com/exercism/java/issues/697)]
@@ -131,11 +131,11 @@ References: [[1](https://github.com/exercism/java/issues/697)]
 > According to the starter implementation policy, any exercise with difficulty 4 or lower should have starter implementation.
 > Any exercise with difficulty 5 or above will have no starter implementation (unless its signature is very complicated).
 > This could be confusing to users when tackling their first exercise with difficulty 5 when they are used to starter implementation being provided.
-
+>
 > Therefore a hints.md file should be added to the .meta directory for every exercise with difficulty 5.
 > This file should explain what they need to do when there is no starter implementation.
 > The files should all be the same so you can copy it from any other exercise with difficulty 5, e.g. [flatten-array](https://github.com/exercism/java/tree/main/exercises/pratice/flatten-array/.meta/hints.md).
-
+>
 > We add the file to every exercise with difficulty 5 because the structure of the track means that we don't know which exercise will be the first one without starter implementation that a user will be faced with.
 
 References: [[1](https://github.com/exercism/java/issues/1075)]
@@ -154,14 +154,14 @@ References: [[1](https://github.com/exercism/java/issues/1389)]
 > When an error has occured or a method can't return anything, the canonical data will just mark that as `"expected": null`.
 > This is because error handling varies from language to language, so the canonical data is leaving it up to each language track to decide how to deal with those situations.
 > It doesn't mean that the method needs to return `null`.
-
+>
 > In Java it's considered bad practice to return `null`.
 > If you return `null` then the user of the method has to remember to check for `null` and they have to look at the implementation of the method to find out that this is necessary.
-
+>
 > It's considered best practice to deal with errors and unexpected circumstances by throwing exceptions.
 > If you throw an exception then you force the user to deal with the problem.
 > You can either define your own exception (see [the triangle exercise](https://github.com/exercism/java/blob/main/exercises/practice/triangle/.meta/src/reference/java/TriangleException.java) for an example) or use a predefined one (see [the collatz-conjecture exercise](https://github.com/exercism/java/blob/main/exercises/practice/collatz-conjecture/src/test/java/CollatzCalculatorTest.java) for an example).
-
+>
 > Another option is to use [Optionals](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
 > This can be more suitable if the case you want to deal with isn't an exceptional occurence, but rather an expected scenario, e.g. a search method not finding what it was searching for.
 > See [the word-search exercise](https://github.com/exercism/java/blob/main/exercises/practice/word-search/src/test/java/WordSearcherTest.java) for an example where `Optional` is used.

README.md

@@ -1,7 +1,8 @@
 # Exercism Java Track
 
 [![Configlet](https://github.com/exercism/java/actions/workflows/configlet.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/configlet.yml)
-[![Gradle](https://github.com/exercism/java/actions/workflows/gradle.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/gradle.yml)
+[![Lint](https://github.com/exercism/java/actions/workflows/lint.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/lint.yml)
+[![Build](https://github.com/exercism/java/actions/workflows/build.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/build.yml)
 [![Test](https://github.com/exercism/java/actions/workflows/test.yml/badge.svg)](https://github.com/exercism/java/actions/workflows/test.yml)
 
 Source for Exercism Exercises in Java.

concepts/booleans/about.md

@@ -2,7 +2,7 @@
 
 Booleans in Java are represented by the `boolean` type, which values can be either `true` or `false`.
 
-Java supports three [boolean operators][operators]: 
+Java supports three [boolean operators][operators]:
 
 - `!` (NOT): negates the boolean  
 - `&&` (AND): takes two booleans and results in true if they're both true  

concepts/booleans/introduction.md

@@ -8,7 +8,7 @@ Java supports three boolean operators:
 - `&&` (AND): takes two booleans and results in true if they're both true  
 - `||` (OR): results in true if any of the two booleans is true  
 
-**Examples**
+## Examples
 
 ```java
 !true // => false

concepts/exceptions/about.md

@@ -112,23 +112,23 @@ public class ATM {
 
 In this example, when no exception is thrown, the following is printed:
 
-```
+```text
 Withdrawing 10.0
 Withdrawal succeeded
 Current balance: 5.0
 ```
 
 However, should the `bankAccount.withdraw(amount)` statement throw an `InsufficientBalanceException`, the following is printed:
 
-```
+```text
 Withdrawing 10.0
 Withdrawal failed: insufficient balance
 Current balance: 5.0
 ```
 
 Or, in case an unchecked exception is thrown by the `bankAccount.withdraw(amount)`, the following is printed:
 
-```
+```text
 Withdrawing -10.0
 Withdrawal failed: Cannot withdraw a negative amount
 Current balance: 5.0

concepts/exceptions/introduction.md

@@ -112,23 +112,23 @@ public class ATM {
 
 In this example, when no exception is thrown, the following is printed:
 
-```
+```text
 Withdrawing 10.0
 Withdrawal succeeded
 Current balance: 5.0
 ```
 
 However, should the `bankAccount.withdraw(amount)` statement throw an `InsufficientBalanceException`, the following is printed:
 
-```
+```text
 Withdrawing 10.0
 Withdrawal failed: insufficient balance
 Current balance: 5.0
 ```
 
 Or, in case an unchecked exception is thrown by the `bankAccount.withdraw(amount)`, the following is printed:
 
-```
+```text
 Withdrawing -10.0
 Withdrawal failed: Cannot withdraw a negative amount
 Current balance: 5.0

concepts/for-loops/introduction.md

@@ -45,7 +45,7 @@ for (int i = 1; i <= 4; i++) {
 
 The output would be:
 
-```
+```text
 square of 1 is 1
 square of 2 is 4
 square of 3 is 9

concepts/foreach-loops/about.md

@@ -29,7 +29,7 @@ for(char vowel: vowels) {
 
 which outputs:
 
-```
+```text
 a
 e
 i

concepts/foreach-loops/introduction.md

@@ -29,7 +29,7 @@ for(char vowel: vowels) {
 
 which outputs:
 
-```
+```text
 a
 e
 i

concepts/interfaces/about.md

@@ -124,7 +124,6 @@ Moreover, the concept of [polymorphism can be implemented through interfaces][in
 [so-mocking-interfaces]: https://stackoverflow.com/a/9226437/96167
 [comparable]: https://docs.oracle.com/javase/8/docs/api/java/lang/Comparable.html
 [wiki-test-double]: https://en.wikipedia.org/wiki/Test_double
-[wiki-polymorphism]: https://en.wikipedia.org/wiki/Polymorphism_(computer_science)
 [wiki-namespaces]: https://en.wikipedia.org/wiki/Namespace
 [wiki-loose-coupling]: https://en.wikipedia.org/wiki/Loose_coupling
 [interfaces]: https://docs.oracle.com/javase/tutorial/java/concepts/interface.html

docs/ABOUT.md

@@ -1,17 +1,17 @@
 # About
 
-[Java](https://go.java/index.html) is among the most popular available programming languages, thanks to its versatility and compatibility. 
+[Java](https://go.java/index.html) is among the most popular available programming languages, thanks to its versatility and compatibility.
 It is widely used for software development, mobile applications and developing larger systems.
 
-Java was born in 1995 and is maintained by [Oracle](https://www.oracle.com/index.html). 
-Despite the fact that it isn't as young as some of the fresh languages out there, Java is still really popular. 
-It was designed to be fast, secure, reliable, beginner-friendly and highly portable. 
-This portability perk exists because Java is executed on a cross-platform compatible [Java Virtual Machine - JVM](https://en.wikipedia.org/wiki/Java_virtual_machine). 
-Android apps are also developed using Java, since the [Android Operating System](https://en.wikipedia.org/wiki/Android_(operating_system)) runs on a Java language environment.
+Java was born in 1995 and is maintained by [Oracle](https://www.oracle.com/index.html).
+Despite the fact that it isn't as young as some of the fresh languages out there, Java is still really popular.
+It was designed to be fast, secure, reliable, beginner-friendly and highly portable.
+This portability perk exists because Java is executed on a cross-platform compatible [Java Virtual Machine - JVM](https://en.wikipedia.org/wiki/Java_virtual_machine).
+Android apps are also developed using Java, since the [Android Operating System](<https://en.wikipedia.org/wiki/Android_(operating_system)>) runs on a Java language environment.
 
 The Java community is huge!
-GitHub for example has over 1.5 million Java projects. 
-It's also worth mentioning that Java has the second largest community in [StackOverflow](https://stackoverflow.com/questions/tagged/java)! 
+GitHub for example has over 1.5 million Java projects.
+It's also worth mentioning that Java has the second largest community in [StackOverflow](https://stackoverflow.com/questions/tagged/java)!
 This is important because the larger a programming language community is, the more support you'd be likely to get.
 
 Java also has a powerful and well-designed set of built-in [APIs - Application Programming Interfaces](https://docs.oracle.com/en/java/javase/11/docs/api/index.html), which can be used for various activities like Database connection, networking, I/O, XML parsing, utilities, and much more.