Specify major version number in URLs

[jhildenbiddle]

The HTML rendered by docsify-cli and listed in the Manual Installation section of the official docs results in the very latest version of docsify being loaded by default. This is not only bad practice generally speaking, but it also means that breaking changes introduced in a new major release could break a lot of live docsify sites.

The suggested fix is to specify a major version number in all docsify URLs:

<link rel="stylesheet" href="//unpkg.com/docsify@4/themes/vue.css">
<script src="//unpkg.com/docsify@4/lib/docsify.min.js"></script>

This means that when a new major version is released, site admins will need to manually update the URLs with the new major version number (e.g. @5). The benefit of this approach is that breaking changes in the new release will not affect existing docsify sites since they are loading the previous version.

If URLs are being updated, it's also worth considering the following:

• Use CDN redirect URLs instead of specifying a path for the main lib file
• Specify the URL scheme to avoid unnecessary redirects (i.e use https:// instead of //)
• Switch to jsDelivr (Consider jsDelivr over unpkg for CDN #756) for better CDN performance

<script src="https://cdn.jsdelivr.net/npm/docsify@4/themes/vue.css"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify@4"></script>

[timaschew]

So this issue should be then migrated (or at least linked) to the CLI project, right?

[jhildenbiddle]

It's a valid issue for this repo since the Manual Installation section of the docs needs to be updated, but yes--work will also need to be done in the CLI repo.

I've made a similar issue in the CLI repo.

[trusktr]

Shouldn't this be in the 4.x project board?

[jhildenbiddle]

Yep. Done. 😄