You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://docsify.js.org/)
8
12
9
-
Convert your **docs** folder into a pretty docs website - using [DocsifyJS](https://docsify.js.org/) and some minimal setup instructions. This project's site itself is also running on _DocsifyJS_. :tada:
13
+
Convert your **docs** folder into a pretty docs website - using a lightweight JS library called [DocsifyJS](https://docsify.js.org/) and some minimal set up instructions. This project's site itself is also running on _DocsifyJS_. :tada:
10
14
11
15
?> _DocsifyJS_ is sometimes just called _Docsify_ in this guide. Also known as _Docsify.js_.
12
16
@@ -24,17 +28,17 @@ This project is for you if you answer _yes_ to any of the following:
24
28
- Looking for a template which is based on real world use?
25
29
26
30
27
-
## Setup a _Docsify_ site to run
31
+
## Set up a _Docsify_ site to run
28
32
29
33
This project provides three approaches for choosing a Docsify site to run:
30
34
31
35
- Use the [Quickstart local server](#quickstart-local-server)
32
36
- Clone this repo and start serving the docs repo immediately.
33
37
-[Setup your own docs site](#setup-your-own-docs-site) from scratch
34
-
- Convert your _docs_ directory into a docs site hosted on Github Pages. Copy from some templates files to get up and running with as little effort as possible.
38
+
- Convert your _docs_ directory into a docs site hosted on GitHub Pages. Copy from some templates files to get up and running with as little effort as possible.
35
39
- Use my [DocsifyJS Template](https://github.com/michaelcurrin/docsify-js-template/) repo
36
40
- A minimal template which goes with this tutorial.
37
-
- Click [Use this template](https://img.shields.io/badge/Use_this_template-green.svg?style=for-the-badge) to add a copy to you own repos. you'll be able to starting serving a site on Github Pages or locally.
41
+
- Click [Use this template](https://img.shields.io/badge/Use_this_template-green.svg?style=for-the-badge) to add a copy to you own repos. you'll be able to starting serving a site on GitHub Pages or locally.
38
42
39
43
_Note: The instructions in this repo are intended for Linux and macOS environments._
40
44
@@ -68,7 +72,7 @@ This great [article](https://dev.to/evilmartians/keeping-oss-documentation-with-
68
72
69
73
### My projects
70
74
71
-
-[DocsifyJS Tutorial](https://github.com/michaelcurrin/docsify-js-tutorial/) repo on Github.
75
+
-[DocsifyJS Tutorial](https://github.com/michaelcurrin/docsify-js-tutorial/) repo on GitHub.
- As an alternative to Docsify, try this demo / tutorial / template around MkDocs.
@@ -104,7 +108,7 @@ Main components of a _Docsify_ site:
104
108
- Optional.
105
109
- Describes the menu layout for the **top right menu**.
106
110
107
-
Once you have that setup in _docs_ directory and have pushed to Github, you can setup Github Pages serving the _docs_ directory. Note: _Docsify_ also works with _Netlify_ as per their docs, but this project just considers the Github Pages case.
111
+
Once you have that setup in _docs_ directory and have pushed to GitHub, you can setup GitHub Pages serving the _docs_ directory. Note: _Docsify_ also works with _Netlify_ as per their docs, but this project just considers the GitHub Pages case.
108
112
109
113
### Linking to pages
110
114
@@ -290,7 +294,7 @@ Docsify provides a cover page - a simple page that a visitor sees before scrolli
290
294
291
295
If you want to use it, make sure `coverpage: true` is set in your app config.
292
296
293
-
Then create and edit a *docs/_coverpage.md* file. You can also use the template project's [cover page](https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/docs/_coverpage.md) on Github as a reference.
297
+
Then create and edit a *docs/_coverpage.md* file. You can also use the template project's [cover page](https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/docs/_coverpage.md) on GitHub as a reference.
294
298
295
299
You can add additional buttons to the bottom of the homepage, but there should be no gaps between the lines in your file. And the _last_ one will be solid while the others will be transparent.
296
300
@@ -339,7 +343,7 @@ Not covered here - see [jhildenbiddle/docsify-themeable](https://github.com/jhil
339
343
340
344
Optionally set a theme color. This affects how some content looks, such as quoted blocks, underlined text and buttons. This will default to theme's default if not set manually. i.e. green for _Vue_ and blue for _Buble_.
341
345
342
-
```js
346
+
```javascript
343
347
window.$docsify= {
344
348
themeColor:'#3F51B5',
345
349
};
@@ -413,7 +417,7 @@ Here is a some useful button styling I added to a site. The [Bess CSS Button Gen
413
417
414
418
### 7. Advanced configuration
415
419
416
-
The configuration steps above already get you a prettier and more usable site in my opinion than the barebones one which the _Docsify_`init` command or their _Quickstart_ guide gives you. This section covers advanced steps - you may skip these and jump straight to the [Github Pages](#setup-github-pages-site) section.
420
+
The configuration steps above already get you a prettier and more usable site in my opinion than the barebones one which the _Docsify_`init` command or their _Quickstart_ guide gives you. This section covers advanced steps - you may skip these and jump straight to the [GitHub Pages](#setup-github-pages-site) section.
Load and configure this plugin to add the `Edit on Github` link in the top right of each page (excluding the cover page).
542
+
Load and configure this plugin to add the `Edit on GitHub` link in the top right of each page (excluding the cover page).
539
543
540
-
- [njleonzhang/docsify-edit-on-github](https://github.com/njleonzhang/docsify-edit-on-github) on Github.
544
+
- [njleonzhang/docsify-edit-on-github](https://github.com/njleonzhang/docsify-edit-on-github) on GitHub.
541
545
542
546
543
547
Load this plugin near the end of the `head` tag.
544
548
545
549
!>**Important:** This will **not** work at the end of the body like most plugins, since the plugin's global variable needs be available when the app is configured.
- Set to override the message. e.g. `'Improve this page'` or `'Edit on GitHub'` or `'π Edit this page'`.
620
624
- Example:
621
625
```javascript
622
-
EditOnGithubPlugin.create(
626
+
EditOnGitHubPlugin.create(
623
627
repo,
624
628
null,
625
629
'Improve this page'
626
630
);
627
631
```
628
632
629
633
630
-
## Setup Github Pages site
634
+
## Set up GitHub Pages site
631
635
632
636
If you followed the steps above, you'll have a locally running docs site.
633
637
634
-
Now, commit and push the files to Github.
638
+
Now, commit and push the files to GitHub.
635
639
636
-
Next, edit your repo's setting on Github. Select the option to serve the `docs` directory of the `master` branch as Github Pages site. When you refresh the settings page, then you will see a link to your site there.
640
+
Next, edit your repo's setting on GitHub. Select the option to serve the `docs` directory of the `master` branch as GitHub Pages site. When you refresh the settings page, then you will see a link to your site there.
637
641
638
642
Open the link in the browser.
639
643
@@ -737,7 +741,7 @@ Raw markdown:
737
741
738
742
!> Do not put two embed items in a sequence without some characters in between, otherwise you will get a JS error rending the page. Putting an empty line between them is **not** sufficient.
739
743
740
-
!> If you embed a URL of a Github file, remember to use the _Raw_ URL otherwise you will get an error.
744
+
!> If you embed a URL of a GitHub file, remember to use the _Raw_ URL otherwise you will get an error.
741
745
742
746
743
747
### Use DocsifyJS styling
@@ -858,7 +862,7 @@ This approach is ideal for scoring higher on search engines, as the pre-rendered
858
862
859
863
This command is easy to run locally.
860
864
861
-
Unfortunately this solution does **not** work on static site solutions like Github Pages or Netlify. The Docsify docs recommend using the `now` command to publish a Node.js app for free to [vercel.com/](https://vercel.com/) (previously [zeit.co](https://zeit.co/)).
865
+
Unfortunately this solution does **not** work on static site solutions like GitHub Pages or Netlify. The Docsify docs recommend using the `now` command to publish a Node.js app for free to [vercel.com/](https://vercel.com/) (previously [zeit.co](https://zeit.co/)).
862
866
863
867
864
868
## Static site vs SPA
@@ -873,10 +877,9 @@ See [Server-Side Rendering](https://docsify.js.org/#/ssr) section of the _Docsif
873
877
874
878
I don't think it'll includes a sitemap file.
875
879
876
-
877
880
### Why not use a static site generator?
878
881
879
-
_Docsify_ is a SPA, not a static-site generator.
882
+
_Docsify_ is a SPA, not a static-site generator.Thoughthis should hopefully change when Docsify version 5 comes out.
880
883
881
884
_Jekyll_ and _Hugo_ are excellent options forstatic site generators. They can use themes suited to documentation and they can build off of a _docs_ directory. If you want to read more about those, see my [resources](https://github.com/MichaelCurrin/static-sites-generator-resources) project.
0 commit comments