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

aemmadi · 2020-06-16T16:02:54Z

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)

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.)

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 · 2020-06-16T16:02:58Z

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 · 2020-06-16T16:07:32Z

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:

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
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 · 2020-06-18T16:34:08Z

@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 · 2020-06-21T17:51:05Z

@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 · 2020-06-21T23:48:33Z

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 · 2020-06-22T15:34:30Z

@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>

…ation

jhildenbiddle · 2020-06-22T15:47:37Z

@aemmadi --

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

aemmadi · 2020-06-22T15:49:03Z

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

anikethsaha · 2020-06-23T06:54:03Z

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.

docs/quickstart.md

aemmadi · 2020-06-23T16:34:06Z

@jhildenbiddle Pushed the changes!

jhildenbiddle

Looks great! Nice work, @aemmadi!

anikethsaha · 2020-06-23T16:53:34Z

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

aemmadi · 2020-06-23T17:05:20Z

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

* develop: docs: removed codefund docs and plugin (#1262) docs: remove bundle size from the home page and documentation (#1257) fix: search can not search the table header (#1256) fix: after setting the background image, the button is obscured (#1234) Fix: fixed onlycover flag in mobile (#1243) fix: Updated docs with instructions for installing specific version (fixes #780) (#1225) fix: Add error handling for missing dependencies (fixes #1210) (#1232) [documdocs: deploy docsify in docker. (#1241) docs: Add embed gist instructions to Embed Files (fixes #932 ) (#1238) chore: add changelog 4.11.4 [build] 4.11.4 feat: added html sanitizer for remote rendering (#1128)

feat: Updated docs with instructions for installing specific version

b011bb8

vercel bot deployed to Preview June 16, 2020 16:02 View deployment

aemmadi mentioned this pull request Jun 16, 2020

feat: Included docsify version in url docsifyjs/docsify-cli#107

Merged

Merge branch 'develop' into feature/update-docs-manual-version

6b7870c

vercel bot deployed to Preview June 16, 2020 16:07 View deployment

jhildenbiddle self-requested a review June 17, 2020 18:20

jhildenbiddle requested changes Jun 17, 2020

View reviewed changes

Removed path and name from script tag

9bbc5b8

vercel bot deployed to Preview June 18, 2020 16:28 View deployment

Updated stylesheet with specific version

05753ee

vercel bot deployed to Preview June 18, 2020 16:32 View deployment

jhildenbiddle self-requested a review June 18, 2020 17:23

jhildenbiddle requested changes Jun 18, 2020

View reviewed changes

jhildenbiddle linked an issue Jun 21, 2020 that may be closed by this pull request

Specify major version number in URLs #780

Closed

Formatted and organized headings and html blocks for version specific…

92b0e39

…ation

vercel bot deployed to Preview June 22, 2020 15:47 View deployment

anikethsaha previously approved these changes Jun 22, 2020

View reviewed changes

anikethsaha requested review from jhildenbiddle, Koooooo-7, sy-records and trusktr June 22, 2020 17:45

sy-records previously approved these changes Jun 23, 2020

View reviewed changes

jhildenbiddle requested changes Jun 23, 2020

View reviewed changes

docs/quickstart.md Outdated Show resolved Hide resolved

docs/quickstart.md Outdated Show resolved Hide resolved

Removed html block for latest version

82b80af

aemmadi dismissed stale reviews from sy-records and anikethsaha via 82b80af June 23, 2020 16:33

vercel bot deployed to Preview June 23, 2020 16:33 View deployment

jhildenbiddle approved these changes Jun 23, 2020

View reviewed changes

anikethsaha approved these changes Jun 23, 2020

View reviewed changes

Merge branch 'develop' into feature/update-docs-manual-version

352aac6

vercel bot deployed to Preview June 23, 2020 17:04 View deployment

anikethsaha merged commit b90c948 into docsifyjs:develop Jun 23, 2020

jhildenbiddle mentioned this pull request Jan 30, 2022

Prevent people from importing Docsify without versions in URLs. #1733

Open

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

aemmadi commented Jun 16, 2020 •

edited

Loading

vercel bot commented Jun 16, 2020 •

edited

Loading

codesandbox-ci bot commented Jun 16, 2020 •

edited

Loading

jhildenbiddle left a comment

aemmadi commented Jun 18, 2020

jhildenbiddle left a comment •

edited

Loading

trusktr commented Jun 21, 2020

jhildenbiddle commented Jun 21, 2020 •

edited

Loading

aemmadi commented Jun 22, 2020 •

edited

Loading

jhildenbiddle commented Jun 22, 2020

aemmadi commented Jun 22, 2020

anikethsaha commented Jun 23, 2020

jhildenbiddle left a comment

aemmadi commented Jun 23, 2020

jhildenbiddle left a comment

anikethsaha commented Jun 23, 2020

aemmadi commented Jun 23, 2020

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

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

Conversation

aemmadi commented Jun 16, 2020 • edited Loading

vercel bot commented Jun 16, 2020 • edited Loading

codesandbox-ci bot commented Jun 16, 2020 • edited Loading

jhildenbiddle left a comment

Choose a reason for hiding this comment

aemmadi commented Jun 18, 2020

jhildenbiddle left a comment • edited Loading

Choose a reason for hiding this comment

Manual initialization

trusktr commented Jun 21, 2020

jhildenbiddle commented Jun 21, 2020 • edited Loading

Specifying docsify versions

aemmadi commented Jun 22, 2020 • edited Loading

jhildenbiddle commented Jun 22, 2020

aemmadi commented Jun 22, 2020

anikethsaha commented Jun 23, 2020

jhildenbiddle left a comment

Choose a reason for hiding this comment

aemmadi commented Jun 23, 2020

jhildenbiddle left a comment

Choose a reason for hiding this comment

anikethsaha commented Jun 23, 2020

aemmadi commented Jun 23, 2020

aemmadi commented Jun 16, 2020 •

edited

Loading

vercel bot commented Jun 16, 2020 •

edited

Loading

codesandbox-ci bot commented Jun 16, 2020 •

edited

Loading

jhildenbiddle left a comment •

edited

Loading

jhildenbiddle commented Jun 21, 2020 •

edited

Loading

aemmadi commented Jun 22, 2020 •

edited

Loading