Changelog: Broken Links Checking & Mathematical Notation

This is the second installment of our changelog series. We’re starting the new year with a number of new features. This is also the first release that includes code from an external contributor! Let’s talk about broken links checking and rendering mathematical notation.

Broken links checking

A broken link in the context of documentation refers to a link that points to a page that no longer exists. Finding such links is incredibly frustrating to the reader. They often will end up not finding the information promised in the link, and possibly abandon their task.

Unfortunately broken links are incredibly easy to create. All you need to do is rename a file, and not realise it was referenced by another page.

Luckily, while this is the type of problem that humans are terrible at solving, computers can fix this 100% of the time. Starting from Doctave CLI 0.4.0, our toolchain will check your project’s internal links and make sure they resolve correctly.

While writing your documentation, as you change the content, Doctave will give out warnings that you have broken links:

1
2
3
4
5
6
7
8
9
$ doctave serve

...

WARNING
Detected broken internal links.
The following links point to pages that do not exist:

    features/markdown.md : [I don't exist](/nothing/here)

When you’re ready to publish your documentation, Doctave by default will return a non-zero exit status if it finds broken links in your project.

1
2
3
4
5
6
7
8
$ doctave build --release

...

ERROR: Detected broken internal links.
The following links point to pages that do not exist:

    features/markdown.md : [I don't exist](/nothing/here)

You can ignore the error by passing the --allow-failed-checks flag. More in our own docs.

We have some exciting plans for Doctave.com related to this. We are working towards detecting broken links across your team’s projects, and warning you if cross-project links break. This is a step towards the general goal of giving users feedback about the quality of their documentation over time. Stay tuned for more on this in another post!

Mathematical notation

This is a feature that was requested through Reddit when we first announced the Doctave CLI on the r/rust subreddit. In our latest release, Doctave supports rendering mathematical formulas written in TeX into nicely typeset math notation.

This means the following (note the math language for the code block):

1
2
3
4
5
```math
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq
\left( \sum_{k=1}^n a_k^2 \right)
\left( \sum_{k=1}^n b_k^2 \right)
```

Becomes:

You can read more about it in our documentation.

Other fixes

We also squashed a number of bugs and vastly expanded the number of supported languages in our syntax highlighting system. You can see the list of issues here.

Finally, a big thank you to datdenkikniet for his contributions to this release!

You can find instructions to install Doctave’s latest release here. If you are looking for a place to host your team’s documentation, we suggest taking a look at Doctave.com. It is our specialized hosting provider for Doctave sites, giving you access controls and tools to manage all your documentation with ease.

Happy documenting!