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
Convert your docs folder into a pretty docs website using [Docsify-JS](https://docsify.js.org/) and some minimal setup. This project can be used as a template or reference for your own.
7
7
8
8
My own aim is to turn the docs of many of my existing projects into doc sites with minimal effort to convert them and maintain them.
9
9
10
-
## Basics to get a site working
10
+
_Note: The instructions in this repo for for Linux and Mac environments._
11
+
12
+
## How to serve a docs site with Docsify
11
13
12
14
1. Add a few files to your existing docs folder. You can use this project's files to get you going.
13
15
-**index page** - Homepage of the your docs site. This will setup the app using the _Docsify_ library, set a theme and apply other configurations.
@@ -17,38 +19,93 @@ My own aim is to turn the docs of many of my existing projects into doc sites wi
17
19
18
20
Note that this works _without_ editing your existing docs and _without_ building any HTML pages. The rendering is done on the client-side in a single page application, running on _index.html_.
19
21
20
-
## Setup a site
21
22
22
-
Since the idea is to add to an existing project, is it not that useful to create your own project from this repo. But you should copy the sample files from this project in your own project's docs directory.
23
+
## Quickstart
24
+
25
+
### Setup
26
+
27
+
No installation needed. Just a connection to the internet in order to load the _Docsify_ library in the browser.
- When viewing the site, if you scroll down far enough you will see a hamburger menu which lets you dynamically open or close the sidebar.
23
45
24
-
### Copy files
46
+
##Setup your own docs site
25
47
26
-
TBC
48
+
The idea is to add to an existing project / git repo, so it is not that useful to create your own project from this repo. So rather copy base structure and configs from this project to your own, then customize them for your needs.
Optionally you can set coverpage and sidebar options to `false`, or delete those rows.
31
68
32
69
### Configure sidebar
33
70
34
-
Note file paths are relative to docs directory.
71
+
The sidebar is the menu page on the left of the docs and shows on all page.
72
+
73
+
Use this project's [sidebar](https://raw.githubusercontent.com/MichaelCurrin/docsify-template/master/docs/_sidebar.md) raw file on Github as a reference to edit your own *_sidebar.md* file.
74
+
75
+
The format should be markdown bullet points which can be nested. Include links to you files - note that paths are relative to docs directory.
35
76
36
77
With sidebar enabled and not sidebar details set, your index page will use its own page outline as the menu but with no access to subpages. You might even want your entire site to be a single page based on _README.md_, with section headings added to your menu automatically (no need to maintain sidebar).
37
78
38
-
The top of the side bar will point to the site's root - this will take you to the top of the cover page, rather than the _README.md_. You can create a first item in the sidebar which points to the _README.md_ top element, but that will sort of duplicate having the sidebar heading leading to small confusion for a user. So far attempted with `[Home](README.md#docsify-template)` which gives a funny URL and `[Home](#docsify-template)` which does not load from other pages.
79
+
The top of the side bar will point to the site's root - this will take you to the top of the cover page, rather than the _README.md_. You can create a first item in the sidebar which points to the _README.md_ top element, but that will sort of duplicate having the sidebar heading leading to small confusion for a user.
80
+
81
+
These approaches were attempted but do not work:
39
82
40
-
When viewing the site, if you scroll down far enough you will see a hamburger menu which lets you dynamically open or close the sidebar.
83
+
```
84
+
# This README in the URL when you click on it.
85
+
[Home](README.md#docsify-template)
86
+
87
+
# This is not a valid ID when clicking from a file other than the _docs/README.md_ file.
88
+
[Home](#docsify-template)
89
+
```
41
90
42
91
### Configure cover page
43
92
44
-
TBC
93
+
Use this project's [coverpage](https://raw.githubusercontent.com/MichaelCurrin/docsify-template/master/docs/_coverpage.md) raw file on Github as a reference to edit your own *_coverpage.md* file.
94
+
95
+
You could include a logo image above your project title. For example, you could do this if you have a existent media file.
96
+
97
+
```
98
+
99
+
```
45
100
46
101
### Style
47
102
48
-
Edit _index.html_.
103
+
How to customize the style of your project.
49
104
50
105
#### Color
51
106
107
+
Edit _index.html_.
108
+
52
109
Set a theme color. Defaults to theme's default if not set - green for Vue and blue for Buble.
53
110
54
111
This variable affects how some content looks, such as quoted blocks, underlined text and buttons.
@@ -63,36 +120,45 @@ More on Docsify [theme color](https://docsify.js.org/#/configuration?id=themecol
63
120
64
121
#### Themes
65
122
66
-
Choose a style you like.
123
+
Edit _index.html_.
124
+
125
+
Find the style which is set in the `<head>` tag, which looks like this.
Remove `lib/` from the theme URL to get the uncompressed CSS file.
139
+
You can optionally remove `/lib` from the theme URL to get the _uncompressed_ CSS file.
78
140
79
141
More on Docsify [themes](https://docsify.js.org/#/themes?id=themes) guide.
80
142
81
143
82
-
###Docsify CLI
144
+
## Docsify CLI
83
145
84
-
View the Docsify [Quickstart](https://docsify.js.org/#/quickstart) guide for instructions on setting up the CLI tool and running a site.
146
+
The CLI tool is optional. View the Docsify [Quickstart](https://docsify.js.org/#/quickstart) guide to set up the CLI tool and see how to do the following:
85
147
86
-
The CLI tool is optional and is useful for the following:
87
-
88
-
- Setup an initial _README.md_ (duplicated from project root), _index.html_ and _.nojekyll_ in your a target directory such as _docs_. You can do this by hand or using a template if you don't want the CLI to do it for you.
89
-
- Serve the docs site locally, with hot reload.
148
+
-`init`: Setup an initial _README.md_ (duplicated from project root), _index.html_ and _.nojekyll_ in your a target directory such as _docs_. You can do this by hand or using a template if you don't want the CLI to do it for you.
149
+
-`serve`: Serve the docs site locally, with hot reload.
90
150
91
151
92
152
## Why not a static site generator?
93
153
94
154
Jekyll and Hugo are options for static site generators which 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.
95
155
96
-
A static site generator can be heavy - managing dependencies, building HTML, theming. You might have to add front matter to your doc files. You have to set your menu structure in a similar way to _Docsify_.
156
+
A static site generator can be heavy. There are dependencies (Ruby gems) to manage, HTML to build and a theme to setup (you may lose or gain functionality when switching between Jekyll themes because they use their own templates and layouts). You probably have to add _frontmatter_ to your doc files so they can inherit from layouts and have the correct metadata like title.
157
+
158
+
As with _Docsify_, you will probably have to create a config file which covers the structure of your project for use in the sidebar.
159
+
160
+
Unlike building static files with HTML, with with Docsify there is a single page application running off of a _index.html_ - on each request, a markdown file is fetched by the client and rendered as HTML with a theme and menu. The performance will depend more on the server when serving static HTML pages (prebuild and serve page on the client) or on the client when using a single page application (build structure on the client).
161
+
162
+
Also, the _Docsify_ approach will only work if JavaScript is enabled.
97
163
98
-
Also, with a static site generator you would build HTML files to serve, while with Docsify there is a single page application running off of a _index.html_ - on each request, a markdown file is fetched by the client and rendered as HTML with a theme and menu.
164
+
The _Docsify_site says it supports back to Internet Explorer 11, so that at least helps for a wider audience of users.
0 commit comments