feat: clickable anchor links, enforce asset updates

[tommilligan]

Following discussion here: #16 (comment)

This PR:

• adds clickable anchor links from admonition titles
• adds a mechanism for forcing the user to upgrade their installed CSS files, to allow rollout of breaking changes
  • adds notes to README, that breaking CSS changes may be rolled out on minor version bumps

[tommilligan]

@schungx I would be interested in your opinion on the 'deliberately break mdbook build on minor version updates' approach I've taken here. I think it's not ideal, but I don't see a better way around it at the moment.

An alternative would be to just output the bundled css files again when running mdbook build somehow, though it feels pretty bad to have side effects from running mdbook build.

[schungx]

@schungx I would be interested in your opinion on the 'deliberately break mdbook build on minor version updates' approach I've taken here. I think it's not ideal, but I don't see a better way around it at the moment.

I think it is absolutely OK, as long as these breaks are rare and don't happen often.

If the instructions are clear, then it should be a very minor annoyance.

[tommilligan]

I think it is absolutely OK, as long as these breaks are rare and don't happen often.

Well, I think it has the potential to happen reasonably often when a feature is introduced, if that feature has some visual element.

An alternative would be just to call this a major version bump, so no-one is surprised by something breaking. But I think that's a bit extreme, when no code changes are needed, just to rerun part of the build that could be being rerun all the time in CI anyway.

I think I'll opt for the 'break build on minor version mismatches' and see how many people hate it.

[schungx]

I think I'll opt for the 'break build on minor version mismatches' and see how many people hate it.

You may call it only a "soft break"... as it doesn't affect functionality, only perhaps how it renders.