Docsify

In

Docsify

Definition

  • Docsify generates your documentation website from markdown files on the fly.
  • It does not generate fully static static webpages: it uses online scripts (you can also check docsify-this).

Quick start

  1. Install.

    1
    npm i docsify-cli -g

  2. Initialize (documentation in the ./docs subdirectory).

    1
    docsify init ./docs

  3. Writing content (see the file list in the ./docs subdirectory).

    • index.html: entry file.
    • README.md: home page.
    • .nojekyll: prevents GitHub Pages from ignoring files that begin with an underscore.

  4. Preview your site (on http://localhost:3000).

    1
    docsify serve docs

Index overview

_sidebar.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<!-- index.html -->

<!-- optional loading dialog -->
<div id="app">Please wait...</div>
<!-- end of optional loading dialog -->

<!DOCTYPE html>
<html>
  <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>
</html>
  • Review version: you can check it on both the script and head link for stylesheet, after the ‘@’ character.

Advanced

Several pages

  • Structure.

    1
    2
    3
    4
    5
    6
    7
    .
    └─ docs
      ├─ README.md
      ├─ guide.md
      └─ es-es
        ├─ README.md
        └─ guide.md

  • Paths.

    1
    2
    3
    4
    docs/README.md        => http://domain.com
    docs/guide.md         => http://domain.com/#/guide
    docs/es-es/README.md  => http://domain.com/#/es-es/
    docs/es-es/guide.md   => http://domain.com/#/es-es/guide

  • Structure.

    1
    2
    3
    4
    5
    └─docs/
      ├─ _sidebar.md
      ├─ index.md
      ├─ getting-started.md
      └─ running-services.md

  • Sidebar file content.

    _sidebar.md
    1
    2
    3
    4
    <!-- docs/_sidebar.md -->

    * [Home](/)
    * [Guide](guide.md)

  • Index requires sidebar configuration to true.

    index.html
    1
    2
    3
    4
    5
    6
    7
    8
    <!-- index.html -->

    <script>
    window.$docsify = {
      loadSidebar: true
    }
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

  • Nested sidebars.

    • update after navigation to reflect the current directory by adding a _sidebar.md file to each folder. If the current directory doesn’t have _sidebar.md, it will fall back to the parent directory.

    • update the index file.

      index.html
      1
      2
      3
      4
      5
      6
      7
      8
      <script>
        window.$docsify = {
          loadSidebar: true,
          alias: {
            '/.*/_sidebar.md': '/_sidebar.md'
          }
        }
      </script>

    • Set page titles from sidebar selection to improve SEO.

      _sidebar.md
      1
      2
      3
      <!-- docs/_sidebar.md -->
      * [Home](/)
      * [Guide](guide.md "The greatest guide in the world")

Table of contents

  • Autogeneted by sidebar with subMaxLevel configuration.

    index.html
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <!-- index.html -->

    <script>
      window.$docsify = {
        loadSidebar: true,
        subMaxLevel: 2
      }
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

  • Ignoring specific subheaders: add <!-- {docsify-ignore} --> to it.

    1
    2
    3
    4
    # Getting Started

    ## Header <!-- {docsify-ignore} -->
    This header won't appear in the sidebar table of contents.

  • Ignore all headers: <!-- {docsify-ignore-all} --> on the first header of the page.

    1
    2
    3
    4
    # Getting Started <!-- {docsify-ignore-all} -->

    ## Header
    This header won't appear in the sidebar table of contents.

Custom navbar

  • HTML only: doc links begin with #.

    index.html
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <!-- index.html -->

    <body>
      <nav>
        <a href="#/">EN</a>
        <a href="#/es-es/">ES></a>
      </nav>
      <div id="app"></div>
    </body>

  • Markdown alternative: you can create a custom markdown-based navigation file by setting loadNavbar to true and creating _navbar.md

    index.html
    1
    2
    3
    4
    5
    6
    7
    8
    <!-- index.html -->

    <script>
      window.$docsify = {
        loadNavbar: true
      }
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    _navbar.md
    1
    2
    3
    4
    <!-- _navbar.md -->

    * [En](/)
    * [Es](/es-es/)

  • Nesting.

    _navbar.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    <!-- _navbar.md -->

    * Getting started

      * [Quick start](quickstart.md)
      * [Writing more pages](more-pages.md)
      * [Custom navbar](custom-navbar.md)
      * [Cover page](cover.md)

    * Configuration
      * [Configuration](configuration.md)
      * [Themes](themes.md)
      * [Using plugins](plugins.md)
      * [Markdown configuration](markdown.md)
      * [Language highlight](language-highlight.md)

Cover page

  • Basics.

    index.html
    1
    2
    3
    4
    5
    6
    7
    8
    <!-- index.html -->

    <script>
      window.$docsify = {
        coverpage: true
      }
    </script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    _coverpage.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <!-- _coverpage.md -->

    ![logo](_media/icon.svg)

    # docsify <small>3.5</small>

    > A magical documentation site generator.

    - Simple and lightweight
    - No statically built html files
    - Multiple themes

    [GitHub](https://github.com/docsifyjs/docsify/)
    [Get Started](#docsify)

  • Custom background.

    _coverpage.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    <!-- _coverpage.md -->

    # docsify <small>3.5</small>

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

    <!-- background image -->

    ![](_media/bg.png)

    <!-- background color -->

    ![color](#f0f0f0)

  • Multiple coverpages by level.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    .
    └─docs
      ├─ README.md
      ├─ guide.md
      ├─ _coverpage.md
      └─ es-es
        ├─ README.md
        └─ guide.md
        └─ _coverpage.md

    • general.

      index.html
      1
      2
      3
      window.$docsify = {
        coverpage: ['/', '/es-es/']
      };

    • special filename.

      index.html
      1
      2
      3
      4
      5
      6
      window.$docsify = {
        coverpage: {
          '/': 'cover.md',
          '/es-es/': 'cover.md'
        }
      };

Themes

See Themeable.

1
2
3
4
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

Plugins

Using localstorage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
<script>
  window.$docsify = {
    search: 'auto', // default

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

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

      // Localization
      placeholder: {
        '/es-es/': 'ES',
        '/': 'Type to search',
      },

      noData: 'No Results!',

      // Localization
      noData: {
        '/es-es/': 'ES',
        '/': 'Sin resultados',
      },

      // Headline depth, 1 - 6
      depth: 2,

      hideOtherSidebarContent: false, // whether or not to hide other sidebar content

      // To avoid search index collision
      // between multiple websites under the same domain
      namespace: 'website-1',

      // Use different indexes for path prefixes (namespaces).
      // NOTE: Only works in 'auto' mode.
      //
      // When initialiazing an index, we look for the first path from the sidebar.
      // If it matches the prefix from the list, we switch to the corresponding index.
      pathNamespaces: ['/es-es', '/zh-cn', '/zh-cn/v1'],

      // You can provide a regexp to match prefixes. In this case,
      // the matching substring will be used to identify the index
      pathNamespaces: /^(\/(es-es|zh-cn))?(\/(v1|v2))?/,
    },
  };
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

Emoji

1
2
3
4
5
6
7
8
9
<!-- index.html -->

<script>
  window.$docsify = {
    // ...
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
1
2
3
4
<!-- _navbar.md -->

* [:us:, :uk:](/)
* [:es:](/es-es/)

Copy to clipboard

1
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>