2017-02-12 22:22:33 +08:00
# Quick start
2017-02-21 14:04:16 +08:00
It is recommended to install `docsify-cli` globally, which helps initializing and previewing the website locally.
2017-02-13 22:43:58 +08:00
```bash
npm i docsify-cli -g
```
2017-02-21 14:04:16 +08:00
## Initialize
2017-02-13 22:43:58 +08:00
2017-03-10 05:19:07 +08:00
If you want to write the documentation in the `./docs` subdirectory, you can use the `init` command.
2017-02-13 22:43:58 +08:00
```bash
docsify init ./docs
```
## Writing content
2017-03-10 05:19:07 +08:00
After the `init` is complete, you can see the file list in the `./docs` subdirectory.
2017-02-13 22:43:58 +08:00
2022-03-06 12:25:09 +08:00
- `index.html` as the entry file
- `README.md` as the home page
- `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore
2017-02-13 22:43:58 +08:00
2017-03-25 15:52:21 +08:00
You can easily update the documentation in `./docs/README.md` , of course you can add [more pages ](more-pages.md ).
2017-02-13 22:43:58 +08:00
## Preview your site
2017-02-21 14:04:16 +08:00
Run the local server with `docsify serve` . You can preview your site in your browser on `http://localhost:3000` .
2017-02-13 22:43:58 +08:00
```bash
docsify serve docs
```
2018-07-01 13:48:44 +08:00
?> For more use cases of `docsify-cli` , head over to the [docsify-cli documentation ](https://github.com/docsifyjs/docsify-cli ).
2017-02-13 22:43:58 +08:00
2017-02-21 14:04:16 +08:00
## Manual initialization
2017-02-13 22:43:58 +08:00
2017-03-10 05:19:07 +08:00
If you don't like `npm` or have trouble installing the tool, you can manually create `index.html` :
2017-02-13 22:43:58 +08:00
```html
2017-02-21 14:04:16 +08:00
<!-- index.html -->
2017-02-13 22:43:58 +08:00
<!DOCTYPE html>
< html >
2022-03-06 12:25:09 +08:00
< head >
< meta http-equiv = "X-UA-Compatible" content = "IE=edge,chrome=1" / >
< meta name = "viewport" content = "width=device-width,initial-scale=1" / >
< meta charset = "UTF-8" / >
< link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css"
/>
< / head >
< body >
< div id = "app" > < / div >
< script >
window.$docsify = {
//...
};
< / script >
< script src = "//cdn.jsdelivr.net/npm/docsify@4" > < / script >
< / body >
2017-02-13 22:43:58 +08:00
< / html >
```
2020-06-24 01:11:20 +08:00
### Specifying docsify versions
?> Note that in both of the examples below, 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.
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.
```html
< 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.
```html
2022-03-06 12:25:09 +08:00
< link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify@4.11.4/themes/vue.css"
/>
2020-06-24 01:11:20 +08:00
< script src = "//cdn.jsdelivr.net/npm/docsify@4.11.4" > < / script >
```
### Manually preview your site
2021-07-30 10:18:00 +08:00
If you have Python installed on your system, you can easily use it to run a static server to preview your site.
2017-02-13 22:43:58 +08:00
2021-01-09 22:11:43 +08:00
```python2
2017-02-13 22:43:58 +08:00
cd docs & & python -m SimpleHTTPServer 3000
```
2022-03-06 12:25:09 +08:00
2021-01-09 22:11:43 +08:00
```python3
cd docs & & python -m http.server 3000
```
2017-02-19 08:39:05 +08:00
2017-02-21 14:04:16 +08:00
## Loading dialog
2017-02-19 08:39:05 +08:00
2017-02-21 14:04:16 +08:00
If you want, you can show a loading dialog before docsify starts to render your documentation:
2017-02-19 08:39:05 +08:00
```html
2020-06-24 01:11:20 +08:00
<!-- index.html -->
2017-02-21 14:04:16 +08:00
2020-06-24 01:11:20 +08:00
< div id = "app" > Please wait...< / div >
2017-02-19 08:39:05 +08:00
```
2017-02-21 14:04:16 +08:00
You should set the `data-app` attribute if you changed `el` :
2017-02-19 08:39:05 +08:00
```html
2020-06-24 01:11:20 +08:00
<!-- index.html -->
2017-02-22 21:29:26 +08:00
2020-06-24 01:11:20 +08:00
< div data-app id = "main" > Please wait...< / div >
2017-02-19 08:39:05 +08:00
2022-03-06 12:25:09 +08:00
< script >
window.$docsify = {
el: '#main',
};
< / script >
2017-02-19 08:39:05 +08:00
```
2017-03-10 05:19:07 +08:00
2017-03-25 15:52:21 +08:00
Compare [el configuration ](configuration.md#el ).
