fix: Updated docs with instructions for installing specific version #780

[aemmadi]

Summary
Updated docs with example of using a specific version of docsify while getting started, instead of the default version.

Issue #780 requested changes in the CLI, opened a PR there as well with the changes #107

What kind of change does this PR introduce? (check at least one)

• Bugfix
• Feature
• Code style update
• Refactor
• Docs
• Build-related changes
• Other, please describe:

If changing the UI of default theme, please provide the before/after screenshot:

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

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

• When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

You have tested in the following browsers: (Providing a detailed version will be better.)

• Chrome
• Firefox
• Safari
• Edge
• IE

If adding a new feature, the PR's description includes:

• A convincing reason for adding this feature
• Related documents have been updated
• Related tests have been updated

To avoid wasting your time, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

---

• DO NOT include files inside lib directory.

[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/g5aps4t4l
✅ Preview: https://docsify-previe-git-fork-mlh-fellowship-feature-update-do-3cad02.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 352aac6:

Sandbox	Source
thirsty-platform-5yk47	Configuration

[jhildenbiddle]

Two change requests:

1. Remove the file path and name from the URL:

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

   JSDelivr will automatically deliver the file specified in package.json using the jsdelivr, browser or main property and minify it if necessary. Docsify specifies "main": "lib/docsify.js" in its package.json file, so specifying only //cdn.jsdelivr.net/npm/docsify@4 will result in the minified version of lib/docsify.js being delivered. The reason to do this is because it gives maintainers the ability to change the file location of the main file without requiring an update to the CDN URL. If interested, you can read more about it here: https://www.jsdelivr.com/features#publishing-packages

2. Add a docsify version to the stylesheet as well

   https://github.com/docsifyjs/docsify-cli/blob/22314d392cafc520e575cc2a8a573a72977cc53e/lib/template/index.html#L9

   Should be:

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

   Note here that, unlike above, the full URL (path and filename) are required. This is because only one default file can be specified in package.json.

[aemmadi]

@jhildenbiddle Just pushed the requested changes. Also updated docsify-cli#107 accordingly.

[jhildenbiddle]

Changes look good, but after reading the full doc I realized we need additional changes.

The "Manual Installation" section now contains two blocks of HTML: the first with and the second without @4 in docsify-related URLs. We only want one block of HTML, and that should be the one with @4 in the URLs since the whole point of this change is to lock users to v4 so their site doesn't break when the next major version is released.

Content should be as follow:

Manual initialization

If you don't like npm or have trouble installing the tool, you can manually create index.html:

[Updated HTML with docsify version in URLs]

If you installed python on your system, you can easily use it to run a static server to preview your site.

cd docs && python -m SimpleHTTPServer 3000

[trusktr]

@aemmadi thanks for making this PR!

Besides having only one HTML block I think we should still explicitly mention in the wording outside of the block to highly recommend having a version number.

@aemmadi mind making one more change? to add a note about using the version so that updates "don't break your website"?

[jhildenbiddle]

Good point, @trusktr.

A description of why docsify URLs are locked to a specific version (@4) will be helpful, along with an explanation that URLs will need to be manually updated re receive new major versions. Perhaps presenting sample URL schemes would help illustrate:

---

Specifying docsify versions

Specifying a major version in the URL (@4) will allow your site will receive non-breaking enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch" updates) automatically. This is the recommended way to load docsify resources.

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

If you prefer to lock docsify to a specific version, specify the full version after the @ symbol in the URL. This is the safest way to ensure your site will look and behave the same way regardless of any changes made to future versions of docsify.

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

?> Note that in both of the examples above, docsify URLs will need to be manually updated when a new major version of docsify is released (e.g. v4.x.x => v5.x.x). Check the docsify website periodically to see if a new major version has been released.

---

Thoughts? Too wordy?

BTW, I'm happy to update the docs in a separate PR is that is preferred.

[aemmadi]

@jhildenbiddle

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

<script src="//cdn.jsdelivr.net/npm/docsify@4.11.4/lib/docsify.min.js"></script>

I noticed you used the full file path in jsdelivr, you mentioned in previous comment to remove any file names and paths since jsdelivr takes care of that.

So the src for the <script> tag earlier would be:

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

[jhildenbiddle]

@aemmadi --

Good catch. Sorry about that. Copy/Paste error. I've updated my comment by removing the full path to docsify.min.js.

[aemmadi]

I added all the requested changes and made sub headings to make the doc look aesthetic. Let me know if that works!

[anikethsaha]

cc @jhildenbiddle can you review this as there is one change request from you.

@aemmadi can you rebase with the upstream .

Thanks

[jhildenbiddle]

Hey @aemmadi --

Looks like the wrong block of HTML was deleted. We want to keep the one with the @4 in the URLs.

[aemmadi]

@jhildenbiddle Pushed the changes!

[jhildenbiddle]

Looks great! Nice work, @aemmadi!

[anikethsaha]

idk whats wrong but I cant able to update the branch, @aemmadi can you update your branch .

[aemmadi]

idk whats wrong but I cant able to update the branch, @aemmadi can you update your branch .

Weird, I updated it to the develop branch