mirror of
https://github.com/zhigang1992/docsify.git
synced 2026-05-11 19:42:28 +08:00
Update docs: Getting started (#85)
* fixed look of links in blockquote * updated main README * updated getting started * updated more-pages * make custom sidebar loading clear * updated custom navbar * added markdown comments * updated cover documentation * updated cover page * updated sidebar
This commit is contained in:
Jintzo
13
README.md
13
README.md
@@ -19,7 +19,8 @@
|
||||
- [CLI](https://github.com/QingWei-Li/docsify-cli)
|
||||
|
||||
## Features
|
||||
- Not build static html files
|
||||
|
||||
- No statically built html files
|
||||
- Simple and lightweight (~14kB gzipped)
|
||||
- Smart full-text search plugin
|
||||
- Multiple themes
|
||||
@@ -29,9 +30,9 @@
|
||||
## Quick start
|
||||
Create a `index.html`.
|
||||
|
||||
index.html
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
@@ -47,10 +48,10 @@ index.html
|
||||
|
||||
## Browser Support
|
||||
|
||||
Modern browsers and Internet Explorer 9+.
|
||||
Modern browsers and Internet Explorer 10+.
|
||||
|
||||
## Showcase
|
||||
These open-source projects are using docsify to generate their sites. Pull requests welcome : )
|
||||
These open-source projects are using docsify to generate their sites. Pull requests welcome :blush:
|
||||
|
||||
- [Snipaste](https://docs.snipaste.com/) - Snip & Paste
|
||||
- [puck](https://puck.zz173.com/) - A small & magical php framework.
|
||||
@@ -69,7 +70,7 @@ These open-source projects are using docsify to generate their sites. Pull reque
|
||||
- Create your feature branch: `git checkout -b my-new-feature`
|
||||
- Commit your changes: `git commit -am 'Add some feature'`
|
||||
- Push to the branch: `git push origin my-new-feature`
|
||||
- Submit a pull request :D
|
||||
- Submit a pull request
|
||||
|
||||
|
||||
## Development
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
|
||||
## What is it
|
||||
|
||||
docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. It smartly loads and parses your Markdown files and displays them in website. All you need to do is create an `index.html` to start and [deploy it on GitHub Pages](/deploy).
|
||||
docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. Instead, it smartly loads and parses your Markdown files and displays them as website. All you need to do is create an `index.html` to start and [deploy it on GitHub Pages](/deploy).
|
||||
|
||||
See the [Quick start](/quickstart) for more details.
|
||||
|
||||
## Features
|
||||
|
||||
- Not build static html files
|
||||
- No statically built html files
|
||||
- Simple and lightweight (~14kB gzipped)
|
||||
- Smart full-text search plugin
|
||||
- Multiple themes
|
||||
@@ -19,9 +19,9 @@ See the [Quick start](/quickstart) for more details.
|
||||
|
||||
## Examples
|
||||
|
||||
Check out the [Showcase](https://github.com/QingWei-Li/docsify/#showcase) to see use the docsify generated website.
|
||||
Check out the [Showcase](https://github.com/QingWei-Li/docsify/#showcase) to docsify in use.
|
||||
|
||||
## Donate
|
||||
|
||||
If you think docsify is helpful to you or that my work is valuable. I am happy if you can help me [buy a cup of coffee](https://github.com/QingWei-Li/donate). :heart:
|
||||
Please consider donating if you think docsify is helpful to you or that my work is valuable. I am happy if you can help me [buy a cup of coffee](https://github.com/QingWei-Li/donate). :heart:
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
> A magical documentation site generator.
|
||||
|
||||
- Simple and lightweight (~14kB gzipped)
|
||||
- Not build static html files
|
||||
- No statically built html files
|
||||
- Multiple themes
|
||||
|
||||
|
||||
|
||||
@@ -9,12 +9,12 @@
|
||||
- [Themes](/themes)
|
||||
- [Using plugins](/plugins)
|
||||
- [Markdown configuration](/markdown)
|
||||
- [Lanuage highlight](/language-highlight)
|
||||
- [Lanuage highlighting](/language-highlight)
|
||||
|
||||
- Guide
|
||||
- [Deploy](/deploy)
|
||||
- [Doc helper](/helpers)
|
||||
- [Compatible Vue](/vue)
|
||||
- [Helpers](/helpers)
|
||||
- [Vue compatibility](/vue)
|
||||
- [CDN](/cdn)
|
||||
|
||||
- [Changelog](/changelog)
|
||||
@@ -1,15 +1,14 @@
|
||||
# Cover
|
||||
|
||||
Activate the cover feature by setting `coverpage`. The detail in [Configuration#coverpage](configuration#coverpage).
|
||||
Activate the cover feature by setting `coverpage` to **true**. Details are available in the [coverpage configuration paragraph](configuration#coverpage).
|
||||
|
||||
## Basic usage
|
||||
|
||||
Set `coverpage` to **true**, and create a `_coverpage.md`. You can see the effect in current website.
|
||||
|
||||
|
||||
*index.html*
|
||||
Set `coverpage` to **true**, and create a `_coverpage.md`:
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
coverpage: true
|
||||
@@ -18,33 +17,34 @@ Set `coverpage` to **true**, and create a `_coverpage.md`. You can see the effec
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
*_coverpage.md*
|
||||
|
||||
```markdown
|
||||
<!-- _coverpage.md -->
|
||||
|
||||
|
||||
|
||||
# docsify
|
||||
# docsify <small>3.0</small>
|
||||
|
||||
> A magical documentation site generator.
|
||||
|
||||
- Simple and lightweight (~12kb gzipped)
|
||||
- Simple and lightweight (~14kB gzipped)
|
||||
- No statically built html files
|
||||
- Multiple themes
|
||||
- Not build static html files
|
||||
|
||||
|
||||
[GitHub](https://github.com/QingWei-Li/docsify/)
|
||||
[Get Started](#quick-start)
|
||||
[Get Started](#docsify)
|
||||
```
|
||||
|
||||
!> A document site can have only one cover page.
|
||||
|
||||
## Custom background
|
||||
|
||||
The background color is generated randomly by default. You can customize the background color or image.
|
||||
|
||||
*_coverpage.md*
|
||||
The background color is generated randomly by default. You can customize the background color or image:
|
||||
|
||||
```markdown
|
||||
<!-- _coverpage.md -->
|
||||
|
||||
# docsify
|
||||
|
||||
[GitHub](https://github.com/QingWei-Li/docsify/)
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# Custom navbar
|
||||
|
||||
You can create navbar in HTML file. But note that the link begins with `#/`.
|
||||
## HTML
|
||||
|
||||
*index.html*
|
||||
If you need custom navigation, you can create a HTML-based navigation bar (but note that documentation links begin with `#/`).
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<body>
|
||||
<nav>
|
||||
<a href="#/">EN</a>
|
||||
@@ -14,14 +16,13 @@ You can create navbar in HTML file. But note that the link begins with `#/`.
|
||||
</body>
|
||||
```
|
||||
|
||||
## Writing by Markdown
|
||||
|
||||
You can custom navbar by Markdown file. Set the `loadNavbar` to **true** and create a `_navbar.md`. The detail in [Configuration#load-navbar](configuration#load-navbar).
|
||||
|
||||
*index.html*
|
||||
## Markdown
|
||||
|
||||
Alternatively, you can create a custom markdown-based navigation file by setting `loadNavbar` to **true** and creating `_navbar.md`. Detaile are available in the [load-navbar configuration paragraph](configuration#load-navbar).
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadNavbar: true
|
||||
@@ -30,21 +31,25 @@ You can custom navbar by Markdown file. Set the `loadNavbar` to **true** and cre
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
*_navbar.md*
|
||||
|
||||
|
||||
```markdown
|
||||
<!-- _navbar.md -->
|
||||
|
||||
- [En](/)
|
||||
- [chinese](/zh-cn/)
|
||||
```
|
||||
|
||||
`_navbar.md` is loaded from each level directory. If this directory doesn't have `_navbar.md`, it will fallback to parent directory. For example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`.
|
||||
!> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
|
||||
|
||||
`_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`.
|
||||
|
||||
## Nesting
|
||||
|
||||
You can create sub-lists by indenting items that are under a certain parent.
|
||||
|
||||
```markdown
|
||||
<!-- _navbar.md -->
|
||||
|
||||
- Getting started
|
||||
- [Quick start](/quickstart)
|
||||
- [Writing more pages](/more-pages)
|
||||
@@ -59,7 +64,7 @@ You can create sub-lists by indenting items that are under a certain parent.
|
||||
- [Lanuage highlight](/language-highlight)
|
||||
```
|
||||
|
||||
Example.
|
||||
renders as
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,10 +1,9 @@
|
||||
# More pages
|
||||
|
||||
If you need more pages multi-level routing site. It is easy to achieve in docsify. A simple example: If you create a `guide.md`, then get the route is `/#/guide`.
|
||||
If you need more pages, you can simply create more markdown files in your docsify directory. If you create a file named `guide.md`, then it is accessible via `/#/guide`.
|
||||
|
||||
For example, the directory structure is as follows:
|
||||
|
||||
|
||||
```text
|
||||
-| docs/
|
||||
-| README.md
|
||||
@@ -26,11 +25,13 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide
|
||||
|
||||
## Custom sidebar
|
||||
|
||||
By default, the TOC in sidebar is automatically generated based on Markdown file. You can create a Table of Contents page to list down pages in your site.
|
||||
By default, the table of contents in the sidebar is automatically generated based on your markdown files. If you need a custom sidebar, then you can create your own `sidebar.md` (see [this documentation's sidebar](https://github.com/QingWei-Li/docsify/blob/master/docs/_sidebar.md) for an example):
|
||||
|
||||
First, you need to set `loadSidebar` to **true**. The detail in [Configuration#load-sidebar](configuration#load-sidebar).
|
||||
First, you need to set `loadSidebar` to **true**. Details are available in the [configuration paragraph](configuration#load-sidebar).
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true
|
||||
@@ -39,22 +40,26 @@ First, you need to set `loadSidebar` to **true**. The detail in [Configuration#l
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
Create the `_sidebar.md`
|
||||
Create the `_sidebar.md`:
|
||||
|
||||
```markdown
|
||||
<!-- docs/_sidebar.md -->
|
||||
|
||||
- [Home](/)
|
||||
- [Guide](/guide)
|
||||
```
|
||||
|
||||
!> Need create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
|
||||
!> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
|
||||
|
||||
`_sidebar.md` is loaded from each level directory. If this directory doesn't have `_sidebar.md`, it will fallback to parent directory. For example, the current path is `/guide/quick-start`, the `_sidebar.md` will be loaded from `/guide/_sidebar.md`.
|
||||
`_sidebar.md` is loaded from each level directory. If the current directory doesn't have `_sidebar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_sidebar.md` will be loaded from `/guide/_sidebar.md`.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
Custom sidebar can also be automatically generate TOC by setting `subMaxLevel`. The detail in [Configuration#sub-max-level](configuration#sub-max-level).
|
||||
A custom sidebar can also automatically generate a table of contents by setting a `subMaxLevel`. Details are available in the [max-level configuration paragraph](configuration#sub-max-level).
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<script>
|
||||
window.$docsify = {
|
||||
loadSidebar: true,
|
||||
@@ -62,5 +67,4 @@ Custom sidebar can also be automatically generate TOC by setting `subMaxLevel`.
|
||||
}
|
||||
</script>
|
||||
<script src="//unpkg.com/docsify"></script>
|
||||
```
|
||||
|
||||
```
|
||||
@@ -1,14 +1,14 @@
|
||||
# Quick start
|
||||
|
||||
Recommended install `docsify-cli` globally, which can help us to initialize and preview the website locally.
|
||||
It is recommended to install `docsify-cli` globally, which helps initializing and previewing the website locally.
|
||||
|
||||
```bash
|
||||
npm i docsify-cli -g
|
||||
```
|
||||
|
||||
## initialize
|
||||
## Initialize
|
||||
|
||||
If you want to write the documentation in `./docs` directory, you can use the `init` command.
|
||||
If you want to write the documentation in the `./docs` directory, you can use the `init` command.
|
||||
|
||||
```bash
|
||||
docsify init ./docs
|
||||
@@ -21,28 +21,28 @@ After the init is complete, you can see the file list in the docs directory.
|
||||
|
||||
- `index.html` as the entry file
|
||||
- `README.md` as the home page
|
||||
- `.nojekyll` can prevent GitHub Pages from ignoring files that begin with an underscore
|
||||
- `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore
|
||||
|
||||
You can easily update the documentation in `docs/README.md`, of course you can add [more pages](more-pages).
|
||||
|
||||
## Preview your site
|
||||
|
||||
Run the local server via `docsify serve`. You can preview your site in browser via http://localhost:3000.
|
||||
Run the local server with `docsify serve`. You can preview your site in your browser on `http://localhost:3000`.
|
||||
|
||||
|
||||
```bash
|
||||
docsify serve docs
|
||||
```
|
||||
|
||||
?> More usages of reference [docsify-cli documentation](https://github.com/QingWei-Li/docsify-cli).
|
||||
?> For more use cases of `docsify-cli`, head over to the [docsify-cli documentation](https://github.com/QingWei-Li/docsify-cli).
|
||||
|
||||
## Manually
|
||||
## Manual initialization
|
||||
|
||||
If you don't like npm or feel the trouble to install the tool. What we need is an `index.html`.
|
||||
|
||||
*index.html*
|
||||
If you don't like npm or have trouble installing the tool, you can manually create `index.html`:
|
||||
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
@@ -56,25 +56,27 @@ If you don't like npm or feel the trouble to install the tool. What we need is a
|
||||
</html>
|
||||
```
|
||||
|
||||
If your system has Python, you can easily to run a static server to preview your site.
|
||||
If you installed python on your system, you can easily use it to run a static server to preview your site.
|
||||
|
||||
```bash
|
||||
cd docs && python -m SimpleHTTPServer 3000
|
||||
```
|
||||
|
||||
## Loading tip
|
||||
## Loading dialog
|
||||
|
||||
Show `Loading...` Before starting rendering. You can customize the content.
|
||||
If you want, you can show a loading dialog before docsify starts to render your documentation:
|
||||
|
||||
*index.html*
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<div id="app">Please wait...</div>
|
||||
```
|
||||
|
||||
You should set the `data-app` attribute if you changed `el`.
|
||||
You should set the `data-app` attribute if you changed `el`:
|
||||
|
||||
*index.html*
|
||||
```html
|
||||
<!-- index.html -->
|
||||
|
||||
<div data-app id="main">Please wait...</div>
|
||||
|
||||
<script>
|
||||
|
||||
Reference in New Issue
Block a user