docsify/README.md at e1da2f8a84fcf017137e7c2a310311fca4a62369

test/docsify

Fork 0

mirror of https://gitee.com/docsifyjs/docsify.git synced 2024-11-30 02:58:37 +08:00

qingwei.li e1da2f8a84 docs(README): add search

2017-02-09 21:24:14 +08:00

8.6 KiB

Raw Blame History

Quick Start

Create a project

First create a project, then create a docs folder

mkdir my-project && cd my-project
mkdir docs && cd docs

Create entry file

Create a index.html file

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
</body>
<script src="//unpkg.com/docsify"></script>
</html>

Create README.md as the main page

# Title

## blabla

Deploy!

Push code and activate GitHub Pages via your repo's settings

CLI

Easy to setup and preview a docs.

Install

npm i docsify-cli -g

Setup

Setup a boilerplate docs

docsify init docs

Preview

Preview and serve your docs using

docsify serve docs

Themes

Currently available vue.css and buble.css

<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">

Minified files

<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">

Multiple pages

If you need other pages, directly create the markdown file, such as guide.md is /#/guide.

Code in index.html

<nav>
  <a href="/#/docsify/">En</a>
  <a href="/#/docsify/zh-cn">中文</a>
</nav>

CDN

UNPKG https://unpkg.com/docsify/
jsDelivr http://www.jsdelivr.com/projects/docsify

Cover Page

Generate a cover page with markdown. Create a _coverpage.md and set data-coverpage in the script tag.

![logo](_media/icon.svg)

# docsify <small>1.2.0</small>

> A magical documentation site generator.

- Simple and lightweight (~12kb gzipped)
- Multiple themes
- Not build static html files


[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)

Custom background

Currently the background of the cover page is generated randomly. We can customize the background color, or add a background image.

# docsify <small>1.2.0</small>

> xxx

[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)

<!-- background image -->
![](_media/bg.png)
<!-- background color -->
![color](#f0f0f0)

Markdown parser

Docsify uses marked to parse markdown. We can configure it

window.$docsify = {
  markdown: {
    smartypants: true
  }
}

And it can even be customized

window.$docsify = {
  markdown: function(marked) {
    // ...

    return marked
  }
}

Doc Helpers

p.tip

!> add your content will rendered as <p class="tip">content</p>

!> Important **information**

It will be rendered

<p class="tip">Important <strong>information</strong></p>

e.g.

!> Important information

p.warn

?> todo info

?> todo info

Combining Vue

We can write the Vue syntax directly in the markdown file, when the Vue library is loaded into index.html. Default will automatically initialize a Vue instance, of course, we can also manually.

index.html

<script src="//unpkg.com/vue"></script>
<script src="//unpkg.com/docsify"></script>

<ul>
  <li v-for="i in 10">{{ i }}</li>
</ul>

Manual initialization

<div>
  <input type="text" v-model="msg">
  <p>Hello, {{ msg }}</p>
</div>

<script>
  new Vue({
    el: 'main',
    data: { msg: 'Docsify' }
  })
</script>

Options

You can add configurations in the script tag attributes or with window.$docsify.

repo

Display the GitHub Corner widget.

<script src="//unpkg.com/docsify" data-repo="your/repo"></script>

window.$docsify = {
  repo: 'your/repo'
}

max-level

TOC level.

<script src="//unpkg.com/docsify" data-max-level="6"></script>

window.$docsify = {
  maxLevel: 6
}

el

Root element.

<script src="//unpkg.com/docsify" data-el="#app"></script>

window.$docsify = {
  el: '#app'
}

load-sidebar

Load sidebar markdown file. If it is configured, load the current directory _sidebar.md by default. If the file doesn't exist, the sidebar will appear as a TOC. ** you should add .nojekyll into docs folder to prevent GitHub Pages from ignoring the _sidebar.md**

<script src="/lib/docsify.js" data-load-sidebar></script>

You can specify a file:

<script src="/lib/docsify.js" data-load-sidebar="_sidebar.md"></script>

window.$docsify = {
  loadSidebar: '_sidebar.md'
}

The contents of the file can be:

- [Home](/)
- [Installation](/installation)
- Essentials
  - [Getting Started](/getting-started)
  - [Dynamic Route Matching](/dynamic-matching)
  - [Nested Routes](/nested-routes)

sub-max-level

Display TOC in the custom sidebar. The default value is 0.

<script src="/lib/docsify.js" data-load-sidebar data-max-sub-level="4"></script>

window.$docsify = {
  maxSubLevel: 4
}

Load navbar markdown file. If it is configured, load the current directory _navbar.md by default.

<script src="/lib/docsify.js" data-load-navbar></script>

You can specify a file:

<script src="/lib/docsify.js" data-load-navbar="_navbar.md"></script>

window.$docsify = {
  loadNavbar: '_navbar.md'
}

The contents of the file can be:

- [en](/)
- [chinese](/zh-cn)

If you write a sub level list, it will generate a dropdown list.

- [download](/download)
- language
  - [en](/)
  - [chinese](/zh-cn)

auto2top

Scroll to the top on changing hash.

<script src="/lib/docsify.js" data-auto2top></script>
<!-- Set offset top -->
<script src="/lib/docsify.js" data-auto2top="50"></script>

window.$docsify = {
  auto2top: true,
  // auto2top: 50
}

homepage

README.md will be rendered as a homepage for your website in the docs folder, but sometimes we want to specify another file as a homepage, or even use the README.md in your repo.

<script src="/lib/docsify.js" data-homepage="https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md"></script>
<!-- Or using `Welcome.md` as homepge -->
<script src="/lib/docsify.js" data-homepage="Welcome.md"></script>

window.$docsify = {
  homepage: true
}

base-path

If your HTML entry file and the markdown files are in different directories, we can use:

<script src="/lib/docsify.js" data-base-path="/base/"></script>

<!-- Even if the docs is on another site 😄 -->
<script src="/lib/docsify.js" data-base-path="https://docsify.js.org/"></script>

window.$docsify = {
  basePath: '/base/'
}

coverpage

Generate cover page.

<script src="/lib/docsify.js" data-coverpage></script>
<!-- or -->
<script src="/lib/docsify.js" data-coverpage="other.md"></script>

window.$docsify = {
  coverpage: true
}

name

Project name. It is displayed in the sidebar.

<script src="/lib/docsify.js" data-name="docsify"></script>

window.$docsify = {
  name: 'docsify'
}

name-link

Name link. The default value is window.location.pathname.

<script src="/lib/docsify.js" data-name-link="/"></script>

window.$docsify = {
  nameLink: '/'
}

theme-color

Customize the theme color.

<script src="/lib/docsify.js" data-theme-color="#3F51B5"></script>

window.$docsify = {
  themeColor: '#3F51B5'
}

Plugins

Full Text Search

If a document can have a search, can enhance some user experience. The introduction of search plugin is easy. such as

<script src="//unpkg.com/docsify/lib/docsify.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

By default, the hyperlink on the current page is recognized and the content is saved in localStorage. You can also specify the path to the files.

!> Configure the content before the plugin is installed.

window.$docsify = {
  search: 'auto', // default

  search : [
    '/',            // => /README.md
    '/guide',       // => /guide.md
    '/get-started', // => /get-started.md
    '/zh-cn/',      // => /zh-cn/README.md
  ],

  // Full configuration
  search: {
    maxAge: 86400000, // Expiration time, the default one day
    paths: [], // or 'auto'
    placeholder: 'Type to search'
  }
}

8.6 KiB Raw Blame History