├── LICENSE
├── Makefile
├── README.md
├── README.template.md
├── docs
├── .nojekyll
├── README.md
├── _coverpage.md
├── _sidebar.md
└── index.html
├── replace.sh
└── sample.png
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2020 - 2022 MichaelCurrin
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | .PHONY: docs
2 |
3 | h help:
4 | @grep '^[a-z]' Makefile
5 |
6 | docs:
7 | npx docsify-cli serve docs
8 |
9 | docs-py:
10 | cd docs && python3 -m http.server 3000
11 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # DocsifyJS Template 📒 🕸
2 | > Starter template for a Markdown-based docs site
3 |
4 | [](https://github.com/MichaelCurrin/docsify-js-template/tags/?include_prereleases&sort=semver)
5 | [](#license)
6 |
7 | [](https://docsify.js.org/ "Go to Docsify website")
8 | [](https://pages.github.com/ "Go to GitHub Pages docs")
9 |
10 |
11 | ## Preview
12 |
13 |
22 |
23 | [](https://michaelcurrin.github.io/docsify-js-template/ "Go to website")
24 |
25 | Instead of forking, rather make a new repo using this template button:
26 |
27 | [](https://github.com/MichaelCurrin/docsify-js-template/generate)
28 |
29 |
30 |
31 | If you want to improve the original template, then fork it and make a PR.
32 |
33 |
34 | ## Features
35 |
36 | - 🏭 Template for a SPA modern docs site.
37 | - 📗 Use your awesome project's _existing_ markdown files.
38 | - 🤩 Light on code – just add a single HTML file and optionally add cover page and navbar config.
39 | - 🚀 Easy to host as a static site on GitHub Pages. No build step needed.
40 |
41 |
42 | ## Purpose
43 | > How to use this project
44 |
45 | - Create a **new repo** from the template and host it on GitHub Pages immediately. This is good for trying out Docsify or building a site project from scratch.
46 | - Use this project as a **base** - follow instructions to download just the necessary files to your _existing_ repo's `docs` directory
47 | - View the **live** demo site to see what you'll get.
48 |
49 | For more info on Docsify, see my [DocsifyJS Tutorial][]. That covers intro to DocsifyJS, including installation, running and configuration. If you look at the repo, that has has more content and configuration than this relatively plain template site.
50 |
51 | [DocsifyJS Tutorial]: https://michaelcurrin.github.io/docsify-js-tutorial/#/
52 |
53 |
54 | ## How to use Docsify in your projects
55 |
56 | ### Copy files
57 |
58 | Use one of the approaches below to setup Docsify in your own project.
59 |
60 | #### A. Use this template
61 |
62 | Create a _new_ forked project based on this template by clicking the button below. You'll get a fork in your own repo.
63 |
64 | [](https://github.com/MichaelCurrin/docsify-js-template/generate)
65 |
66 | You could start adding code outside of the _docs_ directory, however this project is intended as a standalone docs site which can be configured for experimentation and used as reference.
67 |
68 | #### B. Add Docsify to an existing project's docs directory
69 |
70 | This will copy the contents of the docs directory from Github to the current folder - ideal if there is an existing project and you want to add to _Docsify_ it.
71 |
72 | 1. Ensure you have `curl` command installed. Or use `wget`.
73 | 2. Navigate to your project's `docs` folder.
74 | ```sh
75 | cd my-project/docs
76 | ```
77 | 3. Download necessary files in the template [docs](/docs) directory to your project using this two-line command. (The `-O` flag will save the files locally, keeping the original filenames.)
78 | ```sh
79 | REPO_DOCS='https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/docs/'
80 | curl $REPO_DOCS\{_coverpage.md,_sidebar.md,.nojekyll,index.html,README.md\} -O
81 | ```
82 |
83 | ### Customize
84 |
85 | You can use your IDE to do find and replace across files.
86 |
87 | Use the convenient [replace.sh](/replace.sh) script in this repo to replace the template's values with your own.
88 |
89 |
90 | 1. Find the script.
91 | - If you used the template button, you've already got it.
92 | - If adding content to your existing project's docs, copy script to your project **root** (not docs directory)
93 | ```sh
94 | curl 'https://raw.githubusercontent.com/MichaelCurrin/docsify-js-template/master/replace.sh' -O
95 | chmod +x ./replace.sh
96 | ```
97 | 2. Modify the `MY_` values then run this script to replace the template's value with your own.
98 | 3. Run the script from the **project root** against yours docs directory.
99 | ```sh
100 | ./replace.sh
101 | ```
102 | 4. The script can be deleted after you use it.
103 |
104 | Now complete any remaining TODO items in the files.
105 |
106 | ### Use template readme
107 |
108 | If you clicked _Use this template_, followed the customize steps above, then the last thing to do is replace the project's README.md file with the template one.
109 |
110 | ```sh
111 | mv README.template.md README.md
112 | ```
113 |
114 | Then customize README.md as your own project.
115 |
116 |
117 | ## Set up and run
118 |
119 | ### Remote use
120 |
121 | Whatever approach you use to set up a `docs` directory, you can use your own project or a forked template and serve your site on platform like GiHhub Pages or Netlify.
122 |
123 | This template still works fine as a standalone online demo of _Docsify_ that you can tweak. In a real project, you'd add your code at the repo root, outside of `docs`. Or you could move your docs site to the repo root on the `gh-pages` branch for GH Pages.
124 |
125 | ### Serve locally
126 |
127 | Follow this [gist](https://gist.github.com/MichaelCurrin/4c8060dcc9d8841f842eeebc7a1436d8) so you can view the docs site on a local webserver.
128 |
129 | Go to my [DocsifyJS Tutorial - Serve locally](https://michaelcurrin.github.io/docsify-js-tutorial/#/?id=serve-a-docsify-site-locally) for more info on what DocsifyJS is and how to use it.
130 |
131 |
132 | ## Related projects
133 |
134 | A template using Docsify Themeable. It is a Docsify site but easier to use, it is prettier (in my opinion), and supports a theme system that is more advanced than that in Docsify.
135 |
136 | - [](https://github.com/MichaelCurrin/docsify-themeable-quickstart)
137 |
138 | A template for Vue-based docs site. Except it uses VuePress to render a static site (better for SEO) rather than as a Single-Page Application like Docsify.
139 |
140 | - [](https://github.com/MichaelCurrin/vuepress-quickstart)
141 |
142 | A template for a Vue-based app.
143 |
144 | - [](https://github.com/MichaelCurrin/vue-quickstart)
145 |
146 |
147 | ## License
148 |
149 | Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).
150 |
151 | - You can modify and reuse this project.
152 | - Please link back to the original repo somewhere in your project if you use this in any way.
153 | - Including an original license copy.
154 | - If you add content from [docs](/docs/) to your repo (or click _Use this template_) and then modify for your own needs so your copy is no longer a template, then you don't need to include a license.
155 | - If you do fork this repo then use it as your own _template_, then this project's license and copyright notice must be **included** with the software. [source](https://choosealicense.com/licenses/#mit). Copy `LICENSE` to `LICENSE-source` and then update your copy of `LICENSE` with your own details.
156 |
--------------------------------------------------------------------------------
/README.template.md:
--------------------------------------------------------------------------------
1 | # My Title
2 | > My subtitle
3 |
4 |
5 | ## Set up and run
6 |
7 | ### Remote use
8 |
9 | 1. Go to the repo on **GitHub**.
10 | 2. Go to the _Settings_ section.
11 | 3. Enable **GitHub Pages** for the _docs_ directory.
12 | 4. Click _environment_ tab on your repo and for the site to build.
13 | 5. On success, click _View deployment_ to see the public URL.
14 | 6. Add the uRL to your Github repo's URL field and your README, to make it easy for people to find.
15 |
16 | ### Serve locally
17 |
18 | To view the docs site on a local web server, follow these instructions - [Serve a docs site locally with DocsifyJS](https://gist.github.com/MichaelCurrin/4c8060dcc9d8841f842eeebc7a1436d8)
19 |
20 |
21 | ## Resources
22 |
23 | For more info on what DocsifyJS is and how to use it, see [DocsifyJS Tutorial](https://michaelcurrin.github.io/docsify-js-tutorial/#/?id=serve-a-docsify-site-locally).
24 |
--------------------------------------------------------------------------------
/docs/.nojekyll:
--------------------------------------------------------------------------------
1 | # This file exists to prevent Github Pages from running Jekyll processing, so that markdown files remain as they are.
2 |
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
1 |
2 | # DocsifyJS Template
3 | > Starter template for a Markdown-based docs site
4 |
5 |
6 | [](https://GitHub.com/MichaelCurrin/docsify-js-template/tags/)
7 | [](https://github.com/MichaelCurrin/docsify-js-template/blob/master/README#license)
8 |
9 | [](https://docsify.js.org/)
10 |
11 |
12 |
13 |
14 | ## About
15 |
16 | This is a template for a simple but elegant docs site built on _Docsify_ which magically turns your markdown in your `docs` directory into a docs site.
17 |
18 | This is a statically-built site - just commit and push and your Github Pages site will re-deploy.
19 |
20 | _Docsify.js_ runs as a _Single-Page Application_ on `index.html` - it relies on JavaScript to pull in content from markdown file, within the app shell. This gives a modern progressive web-app experience for instant page loads. But, this **not** SEO-friendly as crawlers don't like to or can't load JavaScript. So use a static site instead if you need to be found on search engines.
21 |
22 | If you want learn about _Docsify_ and how to customize a docs like this, follow this tutorial:
23 |
24 |
31 |
32 |
33 | ## Create a Docsify site
34 | > How to create your own docs site like this one
35 |
36 | Click the button below to create your own copy of this repo.
37 |
38 |
45 |
46 |
47 |
48 | Then follow instructions in the original GitHub repo linked below. The `README.md` file covers how to set up docs site like this one.
49 |
50 |
16 |
17 | 
29 |
30 | 
43 |
44 | 
55 |
56 |