Switch markdown linter (#10546)

* Add missing permissions

* Switch to new linter

- fix Markdown issues
- remove 404 link in LICENSE.md
- Fix ADR numbering

.github/PULL_REQUEST_TEMPLATE.md

@@ -12,6 +12,7 @@ The title of the PR must not reference an issue, because GitHub does not support
 -->
 
 ### Mandatory checks
+
 - [ ] Change in `CHANGELOG.md` described in a way that is understandable for the average user (if applicable)
 - [ ] Tests created for changes (if applicable)
 - [ ] Manually tested changed features in running JabRef (always required)

.github/workflows/tests.yml

@@ -21,6 +21,9 @@ concurrency:
   group: tests-${{ github.head_ref }}
   cancel-in-progress: true
 
+permissions:
+  pull-requests: write
+
 jobs:
   checkstyle:
     name: Checkstyle
@@ -123,7 +126,7 @@ jobs:
 
               You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "Modernizer".
           comment_tag: modernizer
-  markdown-checks:
+  markdown:
     name: Markdown
     runs-on: ubuntu-latest
     steps:
@@ -132,11 +135,23 @@ jobs:
         with:
           submodules: 'false'
           show-progress: 'false'
-      - name: Run markdown-lint
-        uses: avto-dev/markdown-lint@v1
+      - name: markdownlint-cli2-action
+        uses: DavidAnson/markdownlint-cli2-action@v9
         with:
-          args: CHANGELOG.md CONTRIBUTING.md README.md
-          config: '.markdownlint.yml'
+          globs: |
+            *.md
+            docs/**/*.md
+      - name: Add comment on pull request
+        if: ${{ failure() }}
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          message: >
+              You modified Markdown (*.md) files.
+              To ensure consistent styling, we have [markdown-lint](https://github.com/DavidAnson/markdownlint) in place.
+              [Markdown lint's rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#rules) help to keep our Markdown files consistent within this repository and consistent with the Markdown files outside here.
+
+              You can check the detailed error output at the tab "Checks", section "Tests" (on the left), subsection "Markdown".
+          comment_tag: markdown
   changelog-non-frozen:
     name: CHANGELOG.md
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -1188,4 +1188,4 @@ The changelog of JabRef 2.11 and all previous versions is available as [text fil
 [5.0]: https://github.com/JabRef/jabref/compare/v5.0-beta...v5.0
 [5.0-beta]: https://github.com/JabRef/jabref/compare/v5.0-alpha...v5.0-beta
 [5.0-alpha]: https://github.com/JabRef/jabref/compare/v4.3...v5.0-alpha
-<!-- markdownlint-disable-file MD012 MD024 MD033 -->
+<!-- markdownlint-disable-file MD012 MD024 MD033 MD053 -->

LICENSE.md → LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright © 2003-2023 [JabRef Authors](https://github.com/JabRef/jabref/blob/master/AUTHORS)
+Copyright © 2003-2023 JabRef Authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

PRIVACY.md

@@ -111,10 +111,12 @@ This privacy policy is in effect as of the day mentioned as "last updated" above
 
 ## Contact
 
-If you get in touch with us, we may aks you to provide us with certain personal information (e.g. name and email address) to stay in contact with you.
+If you get in touch with us, we may ask you to provide us with certain personal information (e.g. name and email address) to stay in contact with you.
 For any questions or concerns regarding the privacy policy, please send us an email to <vorstand@jabref.org> or write to
 
 JabRef e.V.  
 Josef-Lanner-Str. 9  
 71069 Sindelfingen  
 Germany
+
+<!-- markdownlint-disable-file MD024 -->

README.md

@@ -99,6 +99,5 @@ For IntelliJ IDEA, just import the project via a Gradle Import by pointing at th
 
 ## Sponsoring
 
-JabRef development is powered by YourKit Java Profiler [![YourKit Java Profiler](https://www.yourkit.com/images/yk_logo.svg)](https://www.yourkit.com/java/profiler/)
-
-[JabRef]: https://www.jabref.org
+JabRef development is powered by YourKit Java Profiler  
+[![YourKit Java Profiler](https://www.yourkit.com/images/yk_logo.svg)](https://www.yourkit.com/java/profiler/)

docs/README.md

@@ -9,7 +9,7 @@ Installing the latest version of ruby followed by `gem install bundler` should b
 
 Afterwards, run
 
-```terminal
+```shell
 bundle install
 jekyll serve --livereload
 ```
@@ -18,7 +18,7 @@ and go to <http://localhost:4000/> in your browser.
 
 On **Windows**, using a dockerized environment is recommended:
 
-```terminal
+```shell
 docker build . -t jrjekyll
 docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv/jekyll jrjekyll jekyll serve -H 0.0.0.0 -t
 ```
@@ -27,3 +27,13 @@ docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv
 * In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun.
 * The current `Dockerfile` is based on <https://github.com/just-the-docs/just-the-docs/blob/main/Dockerfile>.
   The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 2022 (because Ruby was too new).
+
+## Execute linting action
+
+You can execute the linting action as if it was executed by GitHub by executing following command.
+
+```shell
+act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/tests.yml -j "markdown"
+```
+
+That command uses [act](https://github.com/nektos/act), which brings GitHub actions execution to the developer machine.

docs/code-howtos/error-handling.md

@@ -9,16 +9,17 @@ Principles:
 
 * All exceptions we throw should be or extend `JabRefException`; This is especially important if the message stored in the Exception should be shown to the user. `JabRefException` has already implemented the `getLocalizedMessage()` method which should be used for such cases (see details below!).
 * Catch and wrap all API exceptions (such as `IOExceptions`) and rethrow them
-    *   Example:
-
-        ```java
-           try {
-               // ...
-           } catch (IOException ioe) {
-               throw new JabRefException("Something went wrong...",
-                   Localization.lang("Something went wrong...", ioe);
-           }
-        ```
+  * Example:
+
+    ```java
+        try {
+            // ...
+        } catch (IOException ioe) {
+            throw new JabRefException("Something went wrong...",
+                Localization.lang("Something went wrong...", ioe);
+        }
+    ```
+
 * Never, ever throw and catch `Exception` or `Throwable`
 * Errors should only be logged when they are finally caught (i.e., logged only once). See **Logging** for details.
 * If the Exception message is intended to be shown to the User in the UI (see below) provide also a localizedMessage (see `JabRefException`).
@@ -34,6 +35,6 @@ To show error message two different ways are usually used in JabRef:
 * showing an error dialog
 * updating the status bar at the bottom of the main window
 
-```
-TODO: Usage of status bar and Swing Dialogs
+```text
+TODO: Usage of status bar and `DialogService`
 ```

docs/code-howtos/http-server.md

@@ -17,7 +17,9 @@ Howto for Windows - other operating systems work similar:
 
 Note: If you do not do this, you get following error message:
 
-    Could not find server key store C:\Users\USERNAME\AppData\Local\org.jabref\jabref\ssl\server.p12.
+```text
+Could not find server key store C:\Users\USERNAME\AppData\Local\org.jabref\jabref\ssl\server.p12.
+```
 
 ## Start http server
 
@@ -33,13 +35,15 @@ Does not work.
 
 Current try:
 
-    ./gradlew run -Pcomment=httpserver
+```shell
+./gradlew run -Pcomment=httpserver
+```
 
-However, there are with `ForkJoin` (discussion at https://discuss.gradle.org/t/is-it-ok-to-use-collection-parallelstream-or-other-potentially-multi-threaded-code-within-gradle-plugin-code/28003)
+However, there are with `ForkJoin` (discussion at <https://discuss.gradle.org/t/is-it-ok-to-use-collection-parallelstream-or-other-potentially-multi-threaded-code-within-gradle-plugin-code/28003>)
 
 Gradle output:
 
-```
+```shell
 > Task :run
 2023-04-22 11:30:59 [main] org.jabref.http.server.Server.main()
 DEBUG: Libraries served: [C:\git-repositories\jabref-all\jabref\src\main\resources\org\jabref\http\server\http-server-demo.bib]
@@ -51,7 +55,7 @@ DEBUG: Starting server...
 
 IntelliJ output, if `org.jabref.http.server.Server#main` is executed:
 
-```
+```shell
 DEBUG: Starting server...
 2023-04-22 11:44:59 [ForkJoinPool.commonPool-worker-1] org.glassfish.grizzly.http.server.NetworkListener.start()
 INFO: Started listener bound to [localhost:6051]

docs/code-howtos/index.md

@@ -64,25 +64,26 @@ Global variables should be avoided. Try to pass them as dependency.
 
 ### keywords sync
 
-Database.addDatabaseChangeListener does not work as the DatabaseChangedEvent does not provide the field information. Therefore, we have to use BibtexEntry.addPropertyChangeListener(VetoableChangeListener listener)
+`Database.addDatabaseChangeListener` does not work as the `DatabaseChangedEvent` does not provide the field information.
+Therefore, we have to use `BibtexEntry.addPropertyChangeListener(VetoableChangeListener listener)`.
 
 ## Working with BibTeX data
 
 ### Working with authors
 
-You can normalize the authors using `org.jabref.model.entry.AuthorList.fixAuthor_firstNameFirst(String)`. Then the authors always look nice. The only alternative containing all data of the names is `org.jabref.model.entry.AuthorList.fixAuthor_lastNameFirst(String)`. The other `fix...` methods omit data (like the von parts or the junior information).
+You can normalize the authors using `org.jabref.model.entry.AuthorList.fixAuthor_firstNameFirst(String)`. Then the authors always look nice. The only alternative containing all data of the names is `org.jabref.model.entry.AuthorList.fixAuthor_lastNameFirst(String)`. The other `fix...` methods omit data (like the "von" parts or the junior information).
 
 ## Benchmarks
 
 * Benchmarks can be executed by running the `jmh` gradle task (this functionality uses the [JMH Gradle plugin](https://github.com/melix/jmh-gradle-plugin))
 * Best practices:
-    * Read test input from `@State` objects
-    * Return result of calculations (either explicitly or via a `BlackHole` object)
+  * Read test input from `@State` objects
+  * Return result of calculations (either explicitly or via a `BlackHole` object)
 * [List of examples](https://github.com/melix/jmh-gradle-example/tree/master/src/jmh/java/org/openjdk/jmh/samples)
 
 ## Measure performance
 
-Try out the [YourKit JAva Profiler](https://www.yourkit.com).
+Try out the [YourKit Java Profiler](https://www.yourkit.com).
 
 ## equals
 
@@ -92,7 +93,7 @@ When creating an `equals` method follow:
 2. Use the `instanceof` operator to check if the argument has the correct type. If not, return `false`.
 3. Cast the argument to the correct type.
 4. For each “significant” field in the class, check if that field of the argument matches the corresponding field of this object. If all these tests succeed, return `true` otherwise, return `false`.
-5. When you are finished writing your equals method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent?
+5. When you are finished writing your `equals` method, ask yourself three questions: Is it symmetric? Is it transitive? Is it consistent?
 
 Also, note:
 
@@ -103,4 +104,3 @@ Also, note:
 ## Files and Paths
 
 Always try to use the methods from the nio-package. For interoperability, they provide methods to convert between file and path. [https://docs.oracle.com/javase/tutorial/essential/io/path.html](https://docs.oracle.com/javase/tutorial/essential/io/path.html) Mapping between old methods and new methods [https://docs.oracle.com/javase/tutorial/essential/io/legacy.html#mapping](https://docs.oracle.com/javase/tutorial/essential/io/legacy.html#mapping)
-

docs/code-howtos/javafx.md

@@ -128,7 +128,7 @@ public class AboutDialogView extends BaseDialog<Void>
 @Inject private DialogService dialogService;
 ```
 
-*   It is convenient to load the FXML-view directly from the controller class.
+* It is convenient to load the FXML-view directly from the controller class.
 
     The FXML file is loaded using `ViewLoader` based on the name of the class passed to `view`. To make this convention-over-configuration approach work, both the FXML file and the View class should have the same name and should be located in the same package.
 

docs/code-howtos/jpackage.md

@@ -28,11 +28,12 @@ Sometimes issues with modularity only arise in the installed version and do not
 
 1. Open `build.gradle`, under jlink options remove `--strip-debug`
 2. Build using `jpackageImage` (or let the CI build a new version)
-3.  Modify the `build\image\JabRef\runtime\bin\Jabref.bat` file, replace the last line with
+3. Modify the `build\image\JabRef\runtime\bin\Jabref.bat` file, replace the last line with
 
-    ```
+    ```shell
     pushd %DIR% & %JAVA_EXEC% -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n -p "%~dp0/../app" -m org.jabref/org.jabref.cli.Launcher  %* & popd
     ```
+
 4. Open your IDE and add a "Remote Debugging Configuration" for `localhost:8000`
 5. Start JabRef by running the above bat file
 6. Connect with your IDE using remote debugging

docs/code-howtos/localization.md

@@ -35,9 +35,7 @@ General hints:
 
 The tests check whether translation strings appear correctly in the resource bundles.
 
-1.  Add new `Localization.lang("KEY")` to Java file. Run the `LocalizationConsistencyTest`under (src/test/org.jabref.logic.
-
-    )
+1. Add new `Localization.lang("KEY")` to Java file. Run the `org.jabref.logic.LocalizationConsistencyTest`.
 2. Tests fail. In the test output a snippet is generated which must be added to the English translation file.
 3. Add snippet to English translation file located at `src/main/resources/l10n/JabRef_en.properties`
 4. Please do not add translations for other languages directly in the properties. They will be overwritten by [Crowdin](https://crowdin.com/project/jabref)

docs/code-howtos/logging.md

@@ -43,6 +43,5 @@ In the `.properties` file, this is done for `org.jabref.model.entry.BibEntry`.
 
 ## Further reading
 
-SLF4J also support parameterized logging, e.g. if you want to print out multiple arguments in a log statement use a pair of curly braces (`{}`). 
+SLF4J also support parameterized logging, e.g. if you want to print out multiple arguments in a log statement use a pair of curly braces (`{}`).
 Head to <https://www.slf4j.org/faq.html#logging_performance> for examples.
-

docs/code-howtos/openoffice/ooresult-ooerror/index.md

@@ -99,7 +99,7 @@ with an assumption that at any time exactly one of `result` and `error` is prese
 * Since `OOResult` encodes the state `isOK` in `result.isPresent()` (and equivalently in `errror.isEmpty()`), we cannot allow construction of instances where both values are `isEmpty`.\
   In particular, `OOResult.ok(null)` and `OOResult.error(null)` are not allowed: it would make the state `isOK` ambiguous.\
   It would also break the similarity to `Optional` to allow both `isEmpty` and `isOK` to be true.
-*   Not allowing null, has a consequence on `OOResult<Void,E>`\
+* Not allowing null, has a consequence on `OOResult<Void,E>`\
     According to [baeldung.com/java-void-type](https://www.baeldung.com/java-void-type), the only possible value for `Void` is `null` which we excluded.
 
     `OOResult<Void,E>.ok(null)` would look strange: in this case we need `ok()` without arguments.

docs/code-howtos/openoffice/overview.md

@@ -65,7 +65,7 @@ A group of parenthesized citations share the parentheses around, like this:\
 
 From the user's point of view, citation groups can be created by
 
-1.  Selecting multiple entries in a bibliography database, then
+1. Selecting multiple entries in a bibliography database, then
 
     * `[click:Cite]` or
     * `[click:Cite in-text]` or
@@ -140,8 +140,8 @@ The order of appearance of citations (as considered during numbering and adding
 
 The order of citations within a citation group is controlled by `jstyle:MultiCiteChronological`.
 
-* true asks for (year, author, title) ordering,
-* false for (author, year, title).
+* `true` asks for (year, author, title) ordering,
+* `false` for (author, year, title).
 * (There is no option for "in the order provided by the user").
 
 For author-year citation styles this ordering is used directly.
@@ -159,21 +159,21 @@ The location of each citation group in the document is provided by the user. In
 #### Order of the citations
 
 * `globalOrder` and `localOrder` together provide the order of appearance of citations
-*   This also provides the order of first appearance of the cited sources.
+* This also provides the order of first appearance of the cited sources.
 
-    First appearance order of sources is used
+  First appearance order of sources is used
 
-    * in `jstyle:IsSortByPosition` numbered styles
-    * in author-year styles: first appearance of "Smith200a" should precede that of "Smith200b".\
-      To achieve this, the sources get the letters according the order of their first appearance.
-      * This seems to contradict the statement "The bibliography is sorted in (author, year, title) order" above.\
-        It does not. As of JabRef 5.3 both are true.\
-        Consequence: in the references Smith2000b may precede Smith2000a. ([reported](https://github.com/JabRef/jabref/issues/7805))
-    * Some author-year citation styles prescribe a higher threshold on the number of authors for switching to "FirstAuthor et al." form (`jstyle:MaxAuthors`) at the first citation of a source (`jstyle:MaxAuthorsFirst`)
+  * in `jstyle:IsSortByPosition` numbered styles
+  * in author-year styles: first appearance of "Smith200a" should precede that of "Smith200b".\
+    To achieve this, the sources get the letters according the order of their first appearance.
+    * This seems to contradict the statement "The bibliography is sorted in (author, year, title) order" above.\
+      It does not. As of JabRef 5.3 both are true.\
+      Consequence: in the references Smith2000b may precede Smith2000a. ([reported](https://github.com/JabRef/jabref/issues/7805))
+  * Some author-year citation styles prescribe a higher threshold on the number of authors for switching to "FirstAuthor et al." form (`jstyle:MaxAuthors`) at the first citation of a source (`jstyle:MaxAuthorsFirst`)
 
 ## What is stored in a document (JabRef5.2)
 
-*   Each group of citations has a reference mark.
+* Each group of citations has a reference mark.
 
     (Reference marks are shown in LibreOffice in Navigator, under "References".\
     To show the Navigator: `LibreOffice:[menu:View]/[Navigator]` or `LibreOffice:[key:F5]`)