Prevent people from importing Docsify without versions in URLs.

[trusktr]

Summary

Every new person that starts using Docsify copies the examples, which have no versions in CDN URLs, and makes websites that can easily break. This is not good, and instead we should encourage everyone to use versions by example.

This adds versions to all CDN link examples to prevent people from making websites that are at risk of breaking changes to Docsify, makes it clear that the recommended approach is to use full versions in URLs, and fixes formatting in any files that were modified.

What kind of change does this PR introduce?

Docs

Does this PR introduce a breaking change? (check one)

• Yes
• No

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/docsify-core/docsify-preview/2ac8v7UJvvbAjGwe4hcF4M8chRyD
✅ Preview: https://docsify-preview-git-pin-script-versions-docsify-core.vercel.app

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit ccb7ea8:

Sandbox	Source
docsify-template	Configuration

[sy-records]

Why not @4?

[trusktr]

@4 can introduce even accidental breaking changes.

The idea is to get even the most beginners to avoid breaking changes and they can update when they want to, but more advanced users will know how to use @4 and can accept the risk.

[trusktr]

I think @Koooooo-7's idea below, to replace the version automatically, would be great. Let's go with that approach because then it will behave like @4 for us (for Docsify site), but users will see the full version and will copy/paste that into their projects which is good.

[Koooooo-7]

LGTM.
But It seems we should update release.sh as well, otherwise, there should hv change the version manually in docs at each new release.

[trusktr]

LGTM. But It seems we should update release.sh as well, otherwise, there should hv change the version manually in docs at each new release.

I thought the same. I think it can be a new PR. How should we do it?

1. If we place {{docsifyVersion}} (or something) everywhere, we can find/replace it during publish for the website. The downside is that when viewing the docs on GitHub, version numbers will not be there.
2. Another idea is we could have .docs/ folder, and a build step to output to docs folder. People who edit docs would edit files in .docs/, but people who read docs would view docs/. Downside is double content in the repo.

Any other idea?

I like option 1 better so far. People can just see the website for docs.

[jhildenbiddle]

I do not think this is a good idea, and there is a precedence for not doing this.

Which is a better / more likely scenario:

1. We ship multiple versions of docsify with zero bugs, which users are locked into to save them from future bugs.
2. We ship multiple versions of docsify with one-or-more bugs, for which users can receive fixes with zero work and without breaking their site.

Since there is a 100% chance we will continue to ship versions of Docsify with bugs, I think the second option is better for everyone. It is very easy for docsify site owners to be unaware of bugs that are affecting their site visitors (e.g., a bug only seen when viewing on a mobile device they don't own). Having the ability to deliver new minor versions (with non-breaking bug fixes and enhancements) and patch versions (with non-breaking bug fixes only) is important. This is the whole purpose of semantic versioning. We should be encouraging beginners to user major version locks (i.e. @4 vs @4.12.2) for exactly this reason. Had we done this years ago, think of all of the sites that would still be stuck on less-capable, less-stable versions of docsify v4.

The template in the docs and the output of docsify-cli already include @4 version locks:

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />

<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>

I vote we leave it this way. If we want to help beginners understand how CDN version locks work, we can modify the docs accordingly. Here is a screenshot of the block of text I've added to some of my projects available on CDNs:

---

---

Not saying wave to use that exact text, but something similar would suffice.

[jhildenbiddle]

See comment: #1733 (comment)

[trusktr]

By encouraging full version numbers, when someone encounters that bug situation, they can

• implement an alternative or workaround, staying on the same version, and the site stays in a known condition
• or they can manually update the version number to receive a fix, updating to a new known condition

Like you said, there will always be bugs (all software has bugs), so automatically fixing bugs does not mean we won't introduce new ones. People are going to get annoyed when things randomly break (of course I hope it will happen as little as possible).

The worst thing (from experience) is in-range breaking changes. Those are annoying, and those situations happen too often even though people try hard to breaking releases. What do we do in those cases to avoid the most work? Pin the version. 😃 Might as well do it from the beginning for an important project that wishes to remain in a known working condition.

From another angle, in theory, if there are no breaking changes, then a developer can also update the version once in a while. Better that they do that, perform some testing, then release, in my opinion.

---

Whatever the case, we need to eliminate the fact that too many people use Docsify with no version numbers in their URLs.

So the alternative to these changes is to update all the URLs to having @x instead of @x.x.x.

@docsifyjs/core we need votes.

[jhildenbiddle]

@trusktr --

We need more evidence that there is actually a problem before we consider this change because this change has significant trade-offs and ramifications if implemented. We need to make sure everyone understands these things before calling for a vote.

It's also important to consider how plugins factor into this "lock it all down to avoid breaking sites" strategy since they are probably they most common cause of docsify sites breaking. The proposed strategy only works if everyone abides by it which includes plugin and theme authors.

(I have proposed ways to address issues related to plugins previously, but that is a separate topic. Let me know if interested and we can discuss further on Discord.)

FWIW, I believe our current major version lock @4 has proven successful and everyone will be worse off if we switch to specific version locks in our templates and CLI tools.

Whatever the case, we need to eliminate the fact that too many people use Docsify with no version numbers in their URLs.

How are you determining that "too many people use Docsify with no version numbers in their URLs"?

The worst thing (from experience) is in-range breaking changes. Those are annoying, and those situations happen too often even though people try hard to breaking releases.

How are you determining that Docsify-related in-range breaking changes "happen[s] too often"?

So the alternative to these changes is to update all the URLs to having @x instead of @x.x.x.

Docsify has had major version locks (@4) have been in place for ~2.5 years (see #780, #1225).

How are you determining that Docsify's current major version locks (@4) are a problem?

The worst thing (from experience) is in-range breaking changes. [...] What do we do in those cases to avoid the most work? Pin the version.

I have not had this experience. I have multiple docsify sites that have been up-and-running for years with major version locks on all CDN URLs (docsify and plugins). I have never had to pin a CDN URL to a specific version. Maybe I'm just lucky. Maybe you were unlucky. Both experiences are interesting, but neither prove that a significant, large-scale issue exists or does not exist conclusively.

---

Let's look at some stats to try and provide some insights.

Here are the weekly stats from jsdelivr:

If you prefer, you can query jsDelivr's API directly. Here are stats via the API for v4.12.2:

• https://data.jsdelivr.com/v1/package/npm/[email protected]/stats

The good news is that based on those numbers, 97% people visiting sites that load docsify via jsDelivr are receiving the latest version (4.12.2). If we assume that the people that appear to have manually locked themselves to the last version (4.12.1) will eventually update 4.12.2, then that percentage jumps to 99%. I'd say this this is great! It means most site visitors are receiving the latest-and-greatest, most bug-free, most feature-rich version of Docsify we offer. When we release the next version, we should assume it will be better than 4.12.2 and hope it is adopted quickly as well.

Unfortunately, we have no way of knowing how many sites loading v4.12.2 are doing so because all of the following URLs will resolve to the latest version of docsify and jsDelivr does not provide stats for redirects:

• https://cdn.jsdelivr.net/npm/docsify <== Redirect
• https://cdn.jsdelivr.net/npm/docsify@4 <== Redirect
• https://cdn.jsdelivr.net/npm/[email protected] <== Redirect
• https://cdn.jsdelivr.net/npm/[email protected] <== Stats available
• https://cdn.jsdelivr.net/npm/docsify@latest <== Redirect

When we release the next major version, these stats can offer insight into the number of sites loading docsify CDN URLs without @ versions (i.e. redirecting the latest version). For the first few days after we release v5, we can safely assume the vast majority of CDN traffic to v5 is coming from URLs without version numbers. This is because relatively few new sites will be created and few existing sites will have updates their URLs from @4 to @5 versions. Over time, as new docsify sites are created with @5 CDN URLs and existing sites update their URLs, we will start to see more traffic on v5 and less on v4. As far as I am aware, this window is the only opportunity we will have to roughly estimate the number of docsify sites that are using CDN URLs without any version lock.

[sy-records]

I agree with @jhildenbiddle

[jhildenbiddle]

@trusktr --

when someone encounters that bug situation...

This is the critical difference between locking to a major version vs. a specific version: when a site owner encounters a bug, which also means if a site owner encounters a bug.

Locking to a major version has risks and benefits. Doing so accepts that bugs may exist that affect site visitors that a site owner is unaware of, and it is optimistic about Docsify's ability to publish updates responsibly. Yes, there is the risk of a site going down if a bug or unintentional breaking change is published, but there is the benefit of receiving fixes and enhancements automatically without having to manually check for updates or test on a variety of environments (browsers, operating systems, screen sizes, etc). If the possibility of downtime isn't a deal-breaker, you want your docsify site to remain up-to-date without any effort, or you lack the experience and/or resources to test a site properly, then major version locks work great.

Locking to a specific version also has risks and benefits. It locks your site into a known state -- for better or worse -- that you as the site owner have determined is good enough to meet your needs at that time. It is pessimistic about Docsify's ability to publish updates responsibly or reliably which is the right approach if the possibility of downtime is a deal-breaker. The risk is that there may be bugs that affect site visitors that you are unaware of, and the way to mitigate that risk is by spending time manually checking change logs for noteworthy updates and testing in all environments to make sure your site works as expected.

Which option a site owner chooses is a balance between things like requirements, convenience, testing ability, and confidence in the ecosystem's authors/contributors. For better or worse, we decided a major version lock as the default lock type with a message explaining the benefits of locking to a specific version with instructions for doing so was the right way to go (#780, #1225, #1225 (comment), #1225 (comment)). We can revisit this decision, but this feels like a topic that has been discussed and resolved already, and it is unclear why it is resurfacing now.

There's room for creative solutions here though. Both the website and the CLI can be updated to ask users to choose between the convenience of major version locks and the stability of specific version locks, which would update the template accordingly. We could extend this to also ask users which plugins they want to install and include those CDN URLs as well (also adhering to the version lock type they choose). This would be much more helpful for end users instead of our current system which requires them to copy/paste a template and/or CDN URLs and manually modify markup if they prefer a version lock type that differs from the one we use by default.

Can we close this PR and move on to discussing other solutions like the one mentioned above?

@docsifyjs/core -- Thoughts?

P.S. It's worth mentioning that I helped a Docsify user solve a problem caused a specific version lock just two days ago. See here for details: https://discord.com/channels/713647066802421792/724776593125408780/938871577028743259. This is a perfect example of where locking to a specific version caused a problem that would have been solved by locking to a major version instead.