diff --git a/doc/sphinx/source/tutorials/report.md b/doc/sphinx/source/tutorials/report.md
index d07db2c5b32f12ff097bfb2bcfc605108a441ce0..f3023e3497b40e85f511b5b03d75b975b355b79e 100644
--- a/doc/sphinx/source/tutorials/report.md
+++ b/doc/sphinx/source/tutorials/report.md
@@ -2,15 +2,19 @@
 
 Suppose that we want to generate a custom report that includes plots and
 statistics that are not included as part of the report generated by
-[vp-comparefits](./compare-fits.md). We may be lucky enough to find an example
-runcard that produces what we need in `validphys2/examples`. However, we may
-need to write our own own `yaml` runcard from scratch.
+[`vp-comparefits`](./compare-fits.md). We may be lucky enough to find an example
+runcard that produces what we need in
+[`validphys2/examples`](https://github.com/NNPDF/nnpdf/tree/master/validphys2/examples).
+However, we may need to write our own own [`yaml`](https://yaml.org/) runcard
+from scratch.
 
 Suppose we want to have histograms of the χ2 per replica for some set of
 experimental datasets.
 
-The calling of `validphys` actions are used as normal. The action we are looking
-for is `plot_chi2dist`.
+The calling of [`validphys`](vp-index) actions are used as normal. The action we
+are looking for is
+[`plot_chi2dist`](https://github.com/NNPDF/nnpdf/blob/d79059975e4ef97063c6bdd9f19dfb908586e453/validphys2/src/validphys/dataplots.py#L50).
+Here's an example report that does what we're looking for:
 
 ```yaml
 meta:
@@ -40,13 +44,14 @@ actions_:
 ```
 
 The `report(main=True)` command is what generates the report. We can customize
-the formatting of the report using `markdown` syntax. Note for example that `#
-Histograms of χ2` gives this section where we will find our plot an appropriate
-title.
+the formatting of the report using
+[`markdown`](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+syntax. Note for example that `# Histograms of χ2` gives an appropriate title
+to the section where we will find our plot.
 
 If the `template_text` section of the runcard becomes large and unwieldy, it may
 be preferable to put the information from this section in a separate file. In
-such cases one can create a markdown template file, usually called `template.md`
+such cases one can create a `markdown` template file, usually called `template.md`
 such as
 
 ```md
@@ -65,9 +70,10 @@ where this assumes that `template.md` is in the same folder as that in which you
 execute the `validphys` command.
 
 The `meta` field is important for retrieving the report once it has been
-uploaded to the `vp server`. `title` and `author` are fields that appear when
-browsing through reports while the `keywords` allow quick retrieval of the
-report by the search functionality of the server. Setting appropriate keywords
-is especially important when working on a big project, within which it is likely
-that many reports will be produced. In such cases a `keyword` should be chosen
-for the project and set in each uploaded report.
\ No newline at end of file
+uploaded to the [validphys server](https://vp.nnpdf.science/). `title` and
+`author` are fields that appear when browsing through reports while the
+`keywords` allow quick retrieval of the report by the search functionality of
+the server. Setting appropriate keywords is especially important when working on
+a big project, within which it is likely that many reports will be produced. In
+such cases a `keyword` should be chosen for the project and set in each uploaded
+report.