|
| 1 | +# Docsify Template |
| 2 | +> Live demo of a light docs site built on _docsify-js_ and running on Github Pages |
| 3 | +
|
| 4 | +Convert your docs folder into a pretty docs website using _docsify_ and some minimal setup. This project can be used as a template or reference for your own. |
| 5 | + |
| 6 | +See the [Docsify](https://docsify.js.org/) website. |
| 7 | + |
| 8 | + |
| 9 | +## How it works |
| 10 | + |
| 11 | +Note that this works without editing your existing docs and without building any HTML page. |
| 12 | + |
| 13 | +If you were using a static site generator like Jekyll, you might have to add front matter to your docs, in addition to setting Jekyll config for theme and menu layout. |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Setup |
| 18 | + |
| 19 | +### Overview steps |
| 20 | + |
| 21 | +1. Add a few files to your existing docs folder. You can use this project's files to get you going. |
| 22 | + - **index page** - Homepage of the your docs site. This will setup the app using the _docsify_ library, set a theme and apply other configurations. |
| 23 | + - **sidebar** - Describes your menu layout. As _docsify_ is not aware of directory structure so it may not function as you hope without this file. |
| 24 | + - **cover page** - Optional landing page with background image and minimal text. |
| 25 | +2. Turn your Github repo into a Github pages site which builds from the docs directory. |
| 26 | + |
| 27 | +## Setup a site |
| 28 | + |
| 29 | +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. |
| 30 | + |
| 31 | +TBC - How copy files |
| 32 | + |
| 33 | + |
| 34 | +### Style |
| 35 | + |
| 36 | +Edit _index.html_. |
| 37 | + |
| 38 | +#### Color |
| 39 | + |
| 40 | +Set a theme color. Defaults to green if not set. This affects how some content looks, such as quoted blocks, underlined text and buttons. |
| 41 | + |
| 42 | +```js |
| 43 | +window.$docsify = { |
| 44 | + themeColor: '#3F51B5' |
| 45 | +}; |
| 46 | +``` |
| 47 | + |
| 48 | +More on Docsify [theme color](https://docsify.js.org/#/configuration?id=themecolor). |
| 49 | + |
| 50 | +#### Themes |
| 51 | + |
| 52 | +Choose a style you like. |
| 53 | + |
| 54 | +Options: |
| 55 | + |
| 56 | +- `vue.css` |
| 57 | +- `buble.css` |
| 58 | +- `dark.css` |
| 59 | +- `pure.css` |
| 60 | + |
| 61 | +`<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/<THEME>.css">` |
| 62 | + |
| 63 | +Remove `lib/` from the theme URL to get the uncompressed CSS file. |
| 64 | + |
| 65 | +More on Docsify [themes](https://docsify.js.org/#/themes?id=themes) guide. |
| 66 | + |
| 67 | + |
| 68 | +### Docsify CLI |
| 69 | + |
| 70 | +View the Docsify [Quickstart](https://docsify.js.org/#/quickstart) guide for instructions on setting up the CLI tool and running a site. |
| 71 | + |
| 72 | +The CLI tool is optional and is useful for the following: |
| 73 | +- 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. |
| 74 | +- Serve the docs site locally, with hot reload. |
0 commit comments