Pass markdownlint on tutorials

.markdownlint.yaml

@@ -8,4 +8,12 @@ MD007:
 
 # MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md033.md
 MD033:
-  allowed_elements: ["br", "figure", "table", "figcaption", "em", "sub"]
+  allowed_elements:
+    - br
+    - figure
+    - table
+    - figcaption
+    - em
+    - sub
+    - a
+    - sup

docs/docs/tutorials/preliminaries.md

@@ -6,9 +6,9 @@ analysing and using maximally-localised Wannier functions (MLWFs). As a
 first step, install `wannier90` following the instructions in the
 `README` file of the `wannier90` distribution. For an introduction to
 the theory underlying MLWFs, you are encouraged to refer to the brief
-overview given in the `wannier90` User Guide [@UserGuide], to the two
-seminal papers of Refs. [@marzari-prb97; @souza-prb01], a recent review
-article [@marzari-rmp12] and to a paper [@mostofi-cpc08] describing
+overview given in the `wannier90` [User Guide](../user_guide/introduction.md),
+to the two seminal papers of Refs. [@marzari-prb97; @souza-prb01], a recent
+review article [@marzari-rmp12] and to a paper [@mostofi-cpc08] describing
 `wannier90`.
 
 The following additional programs may be installed in order to visualise
@@ -38,7 +38,7 @@ necessary)
     <http://www.numpy.org><br>
     <http://matplotlib.org>
 
-# Parallel execution
+## Parallel execution
 
 `postw90.x` and `wannier90.x` can
 be run in parallel to speed up the calculations, using the MPI
@@ -60,7 +60,7 @@ mpirun -np 8 postw90.x seedname
 libraries installed on your system: refer to your MPI manual and/or to
 your system administrator for further information).
 
-# About these tutorials
+## About these tutorials
 
 The first part of this collection of tutorials comprises four examples taken from
 Refs. [@marzari-prb97; @souza-prb01]: gallium arsenide, lead, silicon
@@ -90,7 +90,7 @@ including abinit (<http://www.abinit.org>), fleur
 (<https://wiki.fysik.dtu.dk/gpaw/>), VASP (<http://www.vasp.at>), and
 Wien2k (<http://www.wien2k.at>)
 
-# Contact us
+## Contact us
 
 If you have any suggestions regarding ways in which these tutorials may be
 improved, then send us an email.

docs/docs/tutorials/tutorial_1.md

@@ -44,8 +44,9 @@
     ```
 
     and re-running `wannier90`. To visualise the MLWFs we must represent
-    them explicitly on a real space grid (see the [User guide page](../user_guide/wannier90/methodology.md#methodology)). As a
-    consequence, plotting the MLWFs is slower and uses more memory than
+    them explicitly on a real space grid (see the
+    [User guide page](../user_guide/wannier90/methodology.md#methodology)).
+    As a consequence, plotting the MLWFs is slower and uses more memory than
     the minimisation of the spread. The four files that are created
     (`gaas_00001.xsf`, etc.) can be viewed using `XCrySDen`,
     e.g.,
@@ -55,7 +56,6 @@
     ```
 
     !!! hint
-
         Once `XCrySDen` starts, click on `Tools` $\rightarrow$ `Data Grid`
         in order to specify an isosurface value to plot.
 
@@ -78,7 +78,6 @@
     the isosurface (say 0.5). Can you explain what you see?
 
     !!! hint
-
         For a finite k-point mesh, the MLWFs are in fact periodic
         and the period is related to the spacing of the k-point mesh. For
         mesh with $n$ divisions in the $i^{\mathrm{th}}$ direction in the

docs/docs/tutorials/tutorial_14.md

@@ -3,9 +3,12 @@
 - Outline: *Compare the quantum conductance of a periodic linear chain
     of Sodium atoms with that of a defected chain*
 
-- Directories: `tutorials/tutorial14/periodic`<br>
-    &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;  `tutorials/tutorial14/defected`<br>
-    *Files can be downloaded from [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial14)*
+- Directories:
+    - `tutorials/tutorial14/periodic`
+    - `tutorials/tutorial14/defected`
+
+    *Files can be downloaded from
+    [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial14)*
 
 - Input Files
 

docs/docs/tutorials/tutorial_16.md

@@ -86,8 +86,9 @@ want to use it, you can start from step 5 using the files in the
 
     Inspect the output file `Si.wout` and check if the convergence was
     reached both in the disentanglement and in the wannierisation steps
-    (as discussed in further detail in Tutorial [11](tutorial_11.md)). You may also want to
-    plot the Wannier functions and the interpolated band structure.
+    (as discussed in further detail in Tutorial [11](tutorial_11.md)).
+    You may also want to plot the Wannier functions and the interpolated
+    band structure.
 
 6. Run `postw90` to calculate the transport coefficients.\
     `postw90.x Si` (serial execution)\

docs/docs/tutorials/tutorial_17.md

@@ -207,7 +207,8 @@ may want to increase `kslice_2dkmesh`.)
     and without spin-orbit, and note the spin-orbit-induced avoided
     crossings.
 
-- In Tutorial [8](tutorial_8.md#iron-spin-polarized-wfs-dos-projeced-wfs-versus-mlwfs) we obtained MLWFs separately for the up- and down-spin
+- In Tutorial [8](tutorial_8.md#iron-spin-polarized-wfs-dos-projeced-wfs-versus-mlwfs)
+    we obtained MLWFs separately for the up- and down-spin
     channels of bcc Fe without spin-orbit. The Wannier-interpolated DOS
     was therefore automatically separated into minority and majority
     contributions. For a spinor calculation we can still spin-decompose

docs/docs/tutorials/tutorial_18.md

@@ -22,8 +22,8 @@ interface.
 
     - `Fe.win` *The `wannier90` and `postw90` input file*
 
-The sequence of steps below is the same of Tutorial [17](tutorial_17.md). If you have
-already run that example, you can reuse the output files from steps
+The sequence of steps below is the same of Tutorial [17](tutorial_17.md).
+If you have already run that example, you can reuse the output files from steps
 1 — 5, and only step 6 must be carried out again using the new input file
 `Fe.win`.
 
@@ -74,7 +74,9 @@ already run that example, you can reuse the output files from steps
 ## Berry curvature plots
 
 The Berry curvature $\Omega_{\alpha\beta}({\bf k})$ of the occupied
-states is defined in this [equation](../user_guide/postw90/berry.md#mjx-eqn:eq:ahc)  of the User Guide. The following lines
+states is defined in this
+[equation](../user_guide/postw90/berry.md#mjx-eqn:eq:ahc)
+of the User Guide. The following lines
 in `Fe.win` are used to calculate the energy bands and the Berry
 curvature (in bohr$^2$) along high-symmetry lines in $k$-space.
 
@@ -102,8 +104,8 @@ python Fe-bands+curv_z.py
 
 and compare with Fig. 2 of Ref. [@yao-prl04].
 
-In Tutorial [17](tutorial_17.md) we plotted the Fermi lines on the (010) plane $k_y=0$. To
-combine them with a heatmap plot of (minus) the Berry curvature set
+In Tutorial [17](tutorial_17.md) we plotted the Fermi lines on the (010) plane
+$k_y=0$. To combine them with a heatmap plot of (minus) the Berry curvature set
 `kpath = false`, uncomment the following lines in `Fe.win`, re-run
 `postw90`, and issue
 
@@ -224,11 +226,12 @@ Comapare the $\omega\rightarrow 0$ limit with the result obtained
 earlier by integrating the Berry curvature.
 
 !!! note
-
     The calculation of the AHC using `berry_task = kubo` involves a
     truncation of the sum over empty states in the Kubo-Greenwood
-    formula: see description of the keyword [`kubo_eigval_max`]() in the
-    User Guide. As discussed around [the formula for anomalous Hall conductivity](../user_guide/postw90/berry.md#mjx-eqn:eq:ahc) of the User Guide, no truncation is done with `berry_task = ahc`.
+    formula: see description of the keyword `kubo_eigval_max` in the
+    User Guide. As discussed around [the formula for anomalous Hall
+    conductivity](../user_guide/postw90/berry.md#mjx-eqn:eq:ahc) of the
+    User Guide, no truncation is done with `berry_task = ahc`.
 
 Next we plot the MCD spectrum. Following Ref. [@yao-prl04], we plot
 ${\rm Im}[\omega\sigma_{xy}(\hbar\omega)]$, in units of
@@ -250,7 +253,8 @@ plot 'Fe-kubo_A_xy.dat' u 1:(\$1)\*(\$3)\*0.0137 w l
 \-   A crude way to model the influence of heterovalent alloying on the
     AHC is to assume that its only effect is to donate or deplete
     electrons, i.e., to shift the Fermi level of the pure
-    crystal [@yao-prb07]. Recalculate the AHC of bcc Fe for a range of Fermi energies within
+    crystal [@yao-prb07]. Recalculate the AHC of bcc Fe for a range of Fermi
+    energies within
     $\pm 0.5$ eV of the true Fermi level. This calculation can be
     streamlined by replacing in `Fe.win`
 

docs/docs/tutorials/tutorial_19.md

@@ -20,7 +20,8 @@ interface.
 
     - `Fe.win` *The `wannier90` and `postw90` input file*
 
-The sequence of steps below is the same of Tutorials [17](tutorial_17.md) and [18](tutorial_18.md). If you
+The sequence of steps below is the same of Tutorials [17](tutorial_17.md) and
+[18](tutorial_18.md). If you
 have already run one of those tutorials, you can reuse the output files
 from steps 1 — 3 and 5. Steps 4 and 6 should be carried out again using
 the new input files `Fe.pw2wan` and `Fe.win`.

docs/docs/tutorials/tutorial_2.md

@@ -24,9 +24,9 @@
         interpolation only*
 
 The four lowest valence bands in lead are separated in energy from the
-higher conduction states (see bandstructure [plot](#fig:pb-bnd)). The MLWFs of these states have partial
-occupancy. MLWFs describing only the occupied states would be poorly
-localised.
+higher conduction states (see bandstructure [plot](#fig:pb-bnd)). The MLWFs of
+these states have partial
+occupancy. MLWFs describing only the occupied states would be poorly localised.
 
 1. Run `wannier90` to minimise the MLWFs spread
 

docs/docs/tutorials/tutorial_21.md

@@ -8,7 +8,9 @@ interface.
     symmetry-adapted Wannier functions, see R. Sakuma, Phys. Rev. B
     **87**, 235109 (2013).*
 
-- Directory: `tutorials/tutorial21/atom_centered_As_sp/` *Files can be downloaded from [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial21)*
+- Directory: `tutorials/tutorial21/atom_centered_As_sp/` *Files can be
+    downloaded from
+    [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial21)*
 
 - Input Files
 

docs/docs/tutorials/tutorial_27.md

@@ -31,7 +31,7 @@ post-processing code of `Quantum ESPRESSO` (v6.4 or above).
     `pw2wannier90` input files each corresponding to one of the
     scenarios listed in the outline.
 
-### Valence bands
+## Valence bands
 
 In this case we will compute 4 localized WFs
 corresponding to the 4 valence bands of Silicon. These 4 bands
@@ -100,7 +100,7 @@ MLWFs computed from user-defined initial $s$-like projections
 (see Tutorial [11](tutorial_11.md))? Plot these WFs using Vesta. Do they show the
 $\sigma$ character one would expect from chemical arguments?
 
-### Valence bands + conduction bands
+## Valence bands + conduction bands
 
 In this case we will compute 8
 localized WFs corresponding to the 4 valence bands and 4 low-lying
@@ -121,7 +121,8 @@ $f(\varepsilon_{n,\mathbf{k}})$ contains two free parameters $\mu$
 and $\sigma$ and is defined as a complementary error function:
 
 $$
-f(\varepsilon_{n,\mathbf{k}}) = \frac{1}{2}\mathrm{erfc}\left(\frac{\varepsilon_{n,\mathbf{k}} - \mu}{\sigma}\right).
+f(\varepsilon_{n,\mathbf{k}}) = \frac{1}{2}\mathrm{erfc}
+\left(\frac{\varepsilon_{n,\mathbf{k}} - \mu}{\sigma}\right).
 $$
 
 1. Copy the input files `si.scf` and `si_12bands.nscf` from the
@@ -185,7 +186,7 @@ Look at the WFs with Vesta. Can you explain what you
 see? Where do the major lobes of the $sp3$-like WFs point in
 this case?
 
-### Conduction bands only
+## Conduction bands only
 
 In this case we will compute 4 localized WFs
 corresponding to the 4 low-lying conduction bands only. As for the

docs/docs/tutorials/tutorial_28.md

@@ -3,8 +3,9 @@
 - Outline: *Obtain MLWFs for the valence bands of diamond and output
     them in Gaussian cube format*
 
-- Directory: `tutorials/tutorial28/` *The input files for this tutorials
-    are the same as the ones in Tutorial [5](tutorial_5.md) and can be downloaded [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial28)*
+- Directory: `tutorials/tutorial28/` *The input files for this tutorials are the
+    same as the ones in Tutorial [5](tutorial_5.md) and can be downloaded
+    [here](https://github.com/wannier-developers/wannier90/tree/develop/tutorials/tutorial28)*
 
 - Input Files