Add GitHub actions to lint markdown files and check links

.github/workflows/check.yml

@@ -1,10 +1,22 @@
-name: Check
+name: Lint scripts and docs
 on: [push, pull_request]
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
         uses: actions/checkout@v2
-      - name: Run ShellCheck
+      - name: Lint shell scripts (shellcheck)
         uses: ludeeus/action-shellcheck@master
+      - name: Lint markdown files (markdownlint)
+        uses: articulate/actions-markdownlint@v1
+        with:
+          config: .markdownlint.json
+          files: '.'
+          ignore: changelog-entries
+      - name: Check links in markdown files (markdown-link-check)
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'no'
+          config-file: '.markdown-link-check-config.json'

.markdown-link-check-config.json

@@ -0,0 +1,3 @@
+{
+  "aliveStatusCodes": [429, 200]
+}

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+    "MD013": false,
+    "MD033": false
+}

CODE_OF_CONDUCT.md

@@ -1,5 +1,7 @@
 # Contributor Covenant Code of Conduct
 
+<!-- markdownlint-configure-file {"MD034": false } -->
+
 ## Our Pledge
 
 We as members, contributors, and leaders pledge to make participation in our

CONTRIBUTING.md

@@ -8,4 +8,30 @@ and watch out for more specific details in this file.
 
 Instead of directly editing `CHANGELOG.md`, please add a file `123.md`
 in `changelog-entries`, where `123` your pull request number. This helps reduce
-merge conflicts and we will merge these files at the time we release a new version.
+merge conflicts and we will merge these files at the time we release a new version.
+
+## Checking the Markdown files
+
+Every contribution is automatically checked for issues in the `.md` files.
+You can run these tests locally by installing [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)
+from npm:
+
+```bash
+npm install -g markdownlint-cli
+```
+
+If you get any permission errors when trying to install from npm, [set the npm prefix to a local directory](https://stackoverflow.com/a/54170648/2254346).
+
+After installing, you can check all files in the current directory with:
+
+```bash
+markdownlint .
+```
+
+There are also extensions for many editors that automatically check Markdown files with the same system.
+
+## Links in the Markdown files
+
+Please use static links when refering to preCICE resources outside of this repository. While relative paths will also work in the rendered website, they will not work in other contexts.
+
+We check these links automatically, but you can also check them locally with [markdown-link-check](https://github.com/tcort/markdown-link-check), which works similarly to markdownlint.

changelog-entries/169.md

@@ -0,0 +1 @@
+Added GitHub actions to check Markdown files, including broken links. [#169](https://github.com/precice/openfoam-adapter/pull/169)

docs/README.md

@@ -7,11 +7,12 @@ summary: An OpenFOAM function object for CHT, FSI, and fluid-fluid coupled simul
 
 ## What is this?
 
-This preCICE adapter is a plug-in (function object) for OpenFOAM, which can work with any recent version of OpenFOAM (.com / .org, see [supported OpenFOAM versions](adapter-openfoam-support.html)). It supports fluid-structure interaction (fluid part), conjugate heat transfer (fluid and solid parts), and fluid-fluid simulations, while it is also easily extensible.
+This preCICE adapter is a plug-in (function object) for OpenFOAM, which can work with any recent version of OpenFOAM (.com / .org, see [supported OpenFOAM versions](https://precice.org/adapter-openfoam-support.html)). It supports fluid-structure interaction (fluid part), conjugate heat transfer (fluid and solid parts), and fluid-fluid simulations, while it is also easily extensible.
 
 ## What can it do?
 
 This adapter can read/write the following fields:
+
 - Temperature (read + write)
 - Heat flux (read + write)
 - Sink temperature (read + write)
@@ -29,7 +30,7 @@ All features of preCICE are supported, including implicit coupling and nearest-p
 
 ## Try
 
-Here you will find how to [get the adapter](adapter-openfoam-get.html), how to [configure](adapter-openfoam.config.html) a case, how to [extend the adapter](adapter-openfoam-extend.html) to cover additional features, as well as a few notes on [supported OpenFOAM versions](adapter-openfoam-support.html).
+Here you will find how to [get the adapter](https://precice.org/adapter-openfoam-get.html), how to [configure](https://precice.org/adapter-openfoam-config.html) a case, how to [extend the adapter](https://precice.org/adapter-openfoam-extend.html) to cover additional features, as well as a few notes on [supported OpenFOAM versions](https://precice.org/adapter-openfoam-support.html).
 
 ## Learn
 
@@ -42,9 +43,11 @@ our [training session from the 15th OpenFOAM Workshop](https://mediatum.ub.tum.d
 ## Cite
 
 We are currently working on an up-to-date reference paper. Until then, please cite this adapter using [1]:
-```
+
+```text
 Gerasimos Chourdakis. A general OpenFOAM adapter for the coupling library preCICE. Master's thesis, Department of Informatics, Technical University of Munich, 2017.
 ```
+
 For CHT-specific topics, you may want to additionally look into [2] and for FSI into [3].
 
 ### Related literature
@@ -55,8 +58,4 @@ For CHT-specific topics, you may want to additionally look into [2] and for FSI
 
 [3] Derek Risseeuw. [Fluid Structure Interaction Modelling of Flapping Wings](https://repository.tudelft.nl/islandora/object/uuid:70beddde-e870-4c62-9a2f-8758b4e49123). Master's thesis, Faculty of Aerospace Engineering, Delft University of Technology, 2019.
 
-
 {% include disclaimer.html content="This offering is not approved or endorsed by OpenCFD Limited, producer and distributor of the OpenFOAM software via www.openfoam.com, and owner of the OPENFOAM®  and OpenCFD®  trade marks." %}
-
-
-

docs/config.md

@@ -6,17 +6,17 @@ summary: "Write a system/preciceDict, set compatible boundary conditions, and ac
 ---
 
 In order to run a coupled simulation, you need to:
-1. prepare a preCICE configuration file (described in the [preCICE configuration](configuration-overview.html)),
+
+1. prepare a preCICE configuration file (described in the [preCICE configuration](https://www.precice.org/configuration-overview.html)),
 2. prepare an adapter's configuration file,
 3. set the coupling boundaries in the OpenFOAM case,
 4. load the adapter, and
 5. start all the solvers normally, from the same directory, e.g. in two different terminals.
 
-If you prefer, you may find an already prepared case in the [tutorials/](https://github.com/precice/openfoam-adapter/tree/master/tutorials) directory. See also the description of this case in our [Tutorial for CHT: Flow over a heated plate](tutorials-flow-over-heated-plate.html).
+If you prefer, you may find an already prepared case in our [Tutorial for CHT: Flow over a heated plate](https://precice.org/tutorials-flow-over-heated-plate.html).
 
 You may skip the section _"Advanced configuration"_ in the beginning, as it only concerns special cases. You may also find more details in the [Pull Request #105](https://github.com/precice/openfoam-adapter/pull/105), especially for changes regarding the previous, yaml-based configuration format.
 
-
 ## The adapter's configuration file
 
 The adapter is configured via the file `system/preciceDict`. This file is an OpenFOAM dictionary with the following form:
@@ -77,6 +77,7 @@ can be `Temperature`, `Heat-Flux`, `Sink-Temperature`,
 or `Heat-Transfer-Coefficient`. Values like `Sink-Temperature-Domain1` are also allowed.
 For a Dirichlet-Neumann coupling, the `writeData` and `readData` can be
 either:
+
 ```c++
 readData
 (
@@ -88,7 +89,9 @@ writeData
   Temperature
 );
 ```
+
 or:
+
 ```c++
 readData
 (
@@ -100,7 +103,9 @@ writeData
   Heat-Flux
 );
 ```
+
 For a Robin-Robin coupling, we need to write and read both of `Sink-Temperature` and `Heat-Transfer-Coefficient`:
+
 ```c++
 readData
 (
@@ -135,6 +140,7 @@ Read the [OpenFOAM User Guide](https://www.openfoam.com/documentation/user-guide
 * For `readData(Temperature)`, use `type fixedValue` for the `interface` in `0/T`.
 OpenFOAM requires that you also give a (redundant) `value`, but the adapter
 will overwrite it. ParaView uses this value for the initial time. As a placeholder, you can e.g. use the value from the `internalField`.
+
 ```c++
 interface
 {
@@ -145,16 +151,19 @@ interface
 
 * For `readData(Heat-Flux)`, use `type fixedGradient` for the `interface` in `0/T`.
 OpenFOAM requires that you also give a (redundant) `gradient`, but the adapter will overwrite it.
+
 ```c++
 interface
 {
     type            fixedGradient;
     gradient        0;
 }
 ```
+
 * For `readData(Sink-Temperature)` or `Heat-Transfer-Coefficient`, use
 `type mixed` for the `interface` in `0/T`. OpenFOAM requires that you also give (redundant) values for
 `refValue`, `refGradient`, and `valueFraction`, but the adapter will overwrite them.
+
 ```c++
 interface
 {
@@ -168,9 +177,9 @@ interface
 #### FSI
 
 * For `readData(Displacement)` or `DisplacementDelta`, you need the following:
-   * `type movingWallVelocity` for the interface (e.g. `flap`) in `0/U`,
-   * `type fixedValue` for the interface (e.g. `flap`) in the `0/pointDisplacement`, and
-   * `solver displacementLaplacian` in the `constant/dynamicMeshDict`.
+  * `type movingWallVelocity` for the interface (e.g. `flap`) in `0/U`,
+  * `type fixedValue` for the interface (e.g. `flap`) in the `0/pointDisplacement`, and
+  * `solver displacementLaplacian` in the `constant/dynamicMeshDict`.
 
 ```c++
 // File 0/U
@@ -193,8 +202,6 @@ motionSolverLibs    ("libfvMotionSolvers.so");
 solver              displacementLaplacian;
 ```
 
-
-
 ### Load the adapter
 
 To load this adapter, you must include the following in
@@ -210,6 +217,7 @@ functions
     }
 }
 ```
+
 This directs the solver to use the `preciceAdapterFunctionObject` function object,
 which is part of the `libpreciceAdapterFunctionObject.so` shared library.
 The name `preCICE_Adapter` can be arbitrary.
@@ -221,7 +229,8 @@ The name `preCICE_Adapter` can be arbitrary.
 These additional parameters may only concern some users is special cases. Keep reading if you want to use nearest-projection mapping, an incompressible or basic (e.g. laplacianFoam) solver, if you are using a solver with different variable names (e.g. a multiphase solver) or if you are trying to debug a simulation.
 
 ### Nearest-projection mapping
-An example for for nearest-projection mapping is provided in the [nearest-projection tutorial case](tutorials-flow-over-heated-plate-nearest-projection.html). The [preCICE documentation](couple-your-code-defining-mesh-connectivity.html) contains a detailed description of nearest-projection mappings in preCICE. In summary, we need to explicitly enable the `connectivity` option to create edges between the interface mesh points and give them to preCICE:
+
+An example for for nearest-projection mapping is provided in the [nearest-projection tutorial case](https://precice.org/tutorials-flow-over-heated-plate-nearest-projection.html). The [preCICE documentation](https://precice.org/couple-your-code-defining-mesh-connectivity.html) contains a detailed description of nearest-projection mappings in preCICE. In summary, we need to explicitly enable the `connectivity` option to create edges between the interface mesh points and give them to preCICE:
 
 ```c++
 interfaces
@@ -247,13 +256,15 @@ interfaces
   };
 };
 ```
+
 This `connectivity` boolean is optional and defaults to `false`. Note that `connectivity true` can only be used with `locations faceNodes`.
 
 Even if the coupling data is associated to `faceCenters` in the solver, we can select `faceNodes` as locations type: the respective data will be interpolated from faces to nodes. Also, connectivity is only needed and supported for `writeData`. Therefore, we need to split the interface in a "read" and a "write" part, as shown above.
 
 More details about the rationale are given in the following section.
 
 #### Adapter Implementation
+
 Since OpenFOAM is a finite-volume based solver, data is located in the middle of the cell, or on the cell face centers for a coupling interface. Mesh connectivity can be given to preCICE using the methods `setMeshTriangle` and `setMeshEdge`. Using the face centers as arguments for these methods is cumbersome. The main reason is that, although OpenFOAM decomposes the mesh for parallel simulations and distributes the subdomains to different processes, mesh connectivity needs to be defined over the partitioned mesh boundaries. This problem vanishes if we define mesh connectivity based on the face nodes, since boundary nodes can be shared among processors. Therefore, mesh connectivity can only be provided on the face nodes (not on the face centers).
 
 As described already, the data is not stored on the face nodes, but on the face centers. Therefore, we use OpenFOAM functions to interpolate from face centers to face nodes. The following image illustrates the workflow:
@@ -275,6 +286,7 @@ Some solvers may not read all the material properties that are required for a co
 For conjugate heat transfer, the adapter assumes that a solver belongs to one of the following categories: _compressible_, _incompressible_, or _basic_. Most of the solvers belong in the _compressible_ category and do not need any additional information. The other two need one or two extra parameters, in order to compute the heat flux.
 
 For **incompressible solvers** (like the buoyantBoussinesqPimpleFoam), you need to add the density and the specific heat in a `CHT` subdictionary of `preciceDict`. For example:
+
 ```c++
 CHT
 {
@@ -284,12 +296,14 @@ CHT
 ```
 
 For **basic solvers** (like the laplacianFoam), you need to add a constant conductivity:
+
 ```c++
 CHT
 {
     k   [ 1  1 -3 -1 0 0 0 ] 100;
 };
 ```
+
 The value of `k` is connected to the one of `DT` (set in `constant/transportProperties`)
 and depends on the density (`rho [ 1 -3  0  0 0 0 0 ]`) and heat capacity (`Cp  [ 0  2 -2 -1 0 0 0 ]`). The relation between them is `DT = k / rho / Cp`.
 
@@ -298,10 +312,12 @@ and depends on the density (`rho [ 1 -3  0  0 0 0 0 ]`) and heat capacity (`Cp
 The adapter's FSI functionality supports both compressible and incompressible solvers.
 
 For incompressible solvers, it tries to read uniform values for the density and kinematic viscosity (if it is not already available) from the `FSI` subdictionary of `preciceDict`:
+
 ```c++
 nu              nu [ 0 2 -1 0 0 0 0 ] 1e-03;
 rho             rho [1 -3 0 0 0 0 0] 1;
 ```
+
 Notice that here, in contrast to the `CHT` subdict, we need to provide both the keyword (first `nu`) and the word name (second `nu`). We are working on bringing consistency on this.
 
 ### Additional parameters in the adapter's configuration file
@@ -355,7 +371,7 @@ CHT
 The adapter also recognizes a few more parameters, which are mainly used in debugging or development.
 These are optional and expect a `true` or a `false` value. Some or all of these options may be removed in the future.
 
-The user can toggle debug messages at [build time](adapter-openfoam-get.html).
+The user can toggle debug messages at [build time](https://precice.org/adapter-openfoam-get.html).
 
 ## Coupling OpenFOAM with 2D solvers
 

docs/get.md

@@ -7,13 +7,10 @@ summary: "Get the code from GitHub and run ./Allwmake. If this fails, look into
 
 To build the adapter, you need to install a few dependencies and then execute the `Allwmake` script.
 
-## Dependencies
-1. Install [a compatible OpenFOAM distribution](adapter-openfoam-support.html).
-2. Install [preCICE](installation-overview.html)
-
-## Adapter
+1. Install [a compatible OpenFOAM distribution](https://precice.org/adapter-openfoam-support.html).
+2. Install [preCICE](https://precice.org/installation-overview.html).
 3. [Download](https://github.com/precice/openfoam-adapter/archive/master.zip) the adapter _or_ (better) install [git](https://git-scm.com/) and clone this repository: `git clone https://github.com/precice/openfoam-adapter.git`.
-    * [Depending on your OpenFOAM version](adapter-openfoam-support.html), you may need to change to a different git branch.
+    * [Depending on your OpenFOAM version](https://precice.org/adapter-openfoam-support.html), you may need to change to a different git branch.
 4. Execute the build script: `./Allwmake`.
     * See and adjust the configuration in the beginning of the script first, if needed.
     * Check for any error messages and suggestions at the end.
@@ -23,7 +20,7 @@ The `-DADAPTER_DEBUG_MODE` flag inside `ADAPTER_PREP_FLAGS` activates additional
 
 In order to upgrade the adapter, or before you build for another OpenFOAM version, run `./Allclean` first. Get the latest version using `git pull`.
 
-Next: [configure and load the adapter](adapter-openfoam-config.html) or [run a tutorial](tutorials.html).
+Next: [configure and load the adapter](https://precice.org/adapter-openfoam-config.html) or [run a tutorial](https://precice.org/tutorials.html).
 
 ## Troubleshooting
 
@@ -40,7 +37,7 @@ The most important information in these files is the `-I` and `-L` flags used du
 
 If in the beginning of the simulation you get the following warning:
 
-```
+```text
 Starting time loop
 
  --> FOAM Warning :
@@ -73,7 +70,7 @@ This is an info/warning message that is printed when WMake tries to distinguish
 
 ### A header file cannot be found (during compilation)
 
-This is a common problem e.g. when installing dependencies in non-system directories. Have a look in the page [linking to preCICE](installation-linking.html).
+This is a common problem e.g. when installing dependencies in non-system directories. Have a look in the page [linking to preCICE](https://precice.org/installation-linking.html).
 
 ### Rellocation-related errors
 

docs/openfoam-support.md

@@ -24,6 +24,7 @@ As these steps change your `.profile`, you need to log out and in again to make
 OpenFOAM is a project with long history and many forks, of which we try to support as many as possible.
 
 Supported versions:
+
 - OpenFOAM (openfoam.com): [v1706](https://www.openfoam.com/releases/openfoam-v1706/) - [v2012](https://www.openfoam.com/releases/openfoam-v2012/) (or newer)
 - OpenFOAM (openfoam.org): version [5.x](https://openfoam.org/version/5-0/) without changes. You need different branches for the versions [4.0/4.1](https://github.com/precice/openfoam-adapter/tree/OpenFOAM4), [6](https://github.com/precice/openfoam-adapter/tree/OpenFOAM6), [7](https://github.com/precice/openfoam-adapter/tree/OpenFOAM7), [8 (experimental)](https://github.com/precice/openfoam-adapter/pull/130).