docsify Documentation

File: README.md

Docsify turns one or more Markdown files into a Website, with no build process required.

Features

No statically built HTML files
Simple and lightweight
Smart full-text search plugin
Multiple themes
Useful plugin API
Emoji support

Quick Start

Get going fast by using a static web server or GitHub Pages with this ready-to-use Docsify Template, review the quick start tutorial or jump right into a CodeSandbox example site with the button below.

Showcase

A large collection of showcase projects are included in awesome-docsify.

Contributing

See CONTRIBUTING.md.

Backers

Thank you to all our backers! 🙏 [Become a backer]

Contributors

This project exists thanks to all the people who contribute. [Contribute].

License

MIT

File: docs/_media/example-with-yaml.md

author: John Smith date: 2020-1-1

This is from the example-with-yaml.md

File: docs/_coverpage.md

docsify 5.0.0 :id=docsify

A magical documentation site generator

Simple and lightweight
No statically built HTML files
Multiple themes

Get Started
GitHub

Translations
- English
- 简体中文

Getting started
Customization
Guide
- Deploy
- Helpers
- Vue compatibility
- CDN
- Offline Mode (PWA)
- Embed Files
- UI Kit
Upgrading
- v4 to v5

File: docs/adding-pages.md

Adding pages

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
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

Matching routes

text

docs/README.md        => http://domain.com
docs/guide.md         => http://domain.com/#/guide
docs/zh-cn/README.md  => http://domain.com/#/zh-cn/
docs/zh-cn/guide.md   => http://domain.com/#/zh-cn/guide

In order to have a sidebar, you can create your own _sidebar.md (see this documentation's sidebar for an example):

First, you need to set loadSidebar to true. Details are available in the configuration paragraph.

html

<script>
  window.$docsify = {
    loadSidebar: true,
  };
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script>

Create the _sidebar.md:

markdown

- [Home](/)
- [Page 1](page-1.md)

To create section headers:

markdown

- Section Header 1

  - [Home](/)
  - [Page 1](page-1.md)

- Section Header 2

  - [Page 2](page-2.md)
  - [Page 3](page-3.md)

You need to create a .nojekyll in ./docs to prevent GitHub Pages from ignoring files that begin with an underscore.

[!IMPORTANT] Docsify only looks for _sidebar.md in the current folder, and uses that, otherwise it falls back to the one configured using window.$docsify.loadSidebar config.

Example file structure:

text

└── docs/
    ├── _sidebar.md
    ├── index.md
    ├── getting-started.md
    └── running-services.md

Nested Sidebars

You may want the sidebar to update after navigation to reflect the current directory. This can be done by adding a _sidebar.md file to each folder.

_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.

You can specify alias to avoid unnecessary fallback.

html

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md',
    },
  };
</script>

[!IMPORTANT] You can create a README.md file in a subdirectory to use it as the landing page for the route.

A page's title tag is generated from the selected sidebar item name. For better SEO, you can customize the title by specifying a string after the filename.

markdown

- [Home](/)
- [Guide](guide.md 'The greatest guide in the world')

Once you've created _sidebar.md, the sidebar content is automatically generated based on the headers in the markdown files.

A custom sidebar can also automatically generate a table of contents by setting a subMaxLevel, compare subMaxLevel configuration.

html

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

Ignoring Subheaders

When subMaxLevel is set, each header is automatically added to the table of contents by default. If you want to ignore a specific header, add `` to it.

markdown

# Getting Started

## Header 

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

To ignore all headers on a specific page, you can use `` on the first header of the page.

markdown

# Getting Started 

## Header

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

Both and will not be rendered on the page when used.

And the {docsify-ignore} and {docsify-ignore-all} can do the samething as well.

File: docs/cdn.md

CDN

The docsify npm package is auto-published to CDNs with each release. The contents can be viewed on each CDN.

Docsify recommends jsDelivr as its preferred CDN:

https://cdn.jsdelivr.net/npm/docsify/

Other CDNs are available and may be required in locations where jsDelivr is not available:

Specifying versions

Note the @ version lock in the CDN URLs below. This allows specifying the latest major, minor, patch, or specific semver version number.

MAJOR versions include breaking changes
1.0.0 → 2.0.0
MINOR versions include non-breaking new functionality
1.0.0 → 1.1.0
PATCH versions include non-breaking bug fixes
1.0.0 → 1.0.1

Uncompressed resources are available by omitting the .min from the filename.

Latest "major" version

Specifying the latest major version allows your site to receive all non-breaking enhancements ("minor" updates) and bug fixes ("patch" updates) as they are released. This is good option for those who prefer a zero-maintenance way of keeping their site up to date with minimal risk as new versions are published.

[!TIP] When a new major version is released, you will need to manually update the major version number after the @ symbol in your CDN URLs.

html

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/vue.min.css" />


<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script>

Specific version

Specifying an exact version prevents any future updates from affecting your site. This is good option for those who prefer to manually update their resources as new versions are published.

[!TIP] When a new version is released, you will need to manually update the version number after the @ symbol in your CDN URLs.

html

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/[email protected]/dist/themes/addons/vue.min.css" />


<script src="//cdn.jsdelivr.net/npm/[email protected]/dist/docsify.min.js"></script>

File: docs/configuration.md

Configuration

You can configure Docsify by defining window.$docsify as an object:

html

<script>
  window.$docsify = {
    repo: 'docsifyjs/docsify',
    maxLevel: 3,
    coverpage: true,
  };
</script>

The config can also be defined as a function, in which case the first argument is the Docsify vm instance. The function should return a config object. This can be useful for referencing vm in places like the markdown configuration:

html

<script>
  window.$docsify = function (vm) {
    return {
      markdown: {
        renderer: {
          code(code, lang) {
            // ... use `vm` ...
          },
        },
      },
    };
  };
</script>

alias

Type: Object

Set the route alias. You can freely manage routing rules. Supports RegExp.
Do note that order matters! If a route can be matched by multiple aliases, the one you declared first takes precedence.

window.$docsify = {
  alias: {
    '/foo/(.*)': '/bar/$1', // supports regexp
    '/zh-cn/changelog': '/changelog',
    '/changelog':
      'https://raw.githubusercontent.com/docsifyjs/docsify/main/CHANGELOG',

    // You may need this if you use routerMode:'history'.
    '/.*/_sidebar.md': '/_sidebar.md', // See #301
  },
};

Note If you change routerMode to 'history', you may
want to configure an alias for your _sidebar.md and _navbar.md files.

auto2top

Type: Boolean
Default: false

Scrolls to the top of the screen when the route is changed.

window.$docsify = {
  auto2top: true,
};

autoHeader

Type: Boolean
Default: false

If loadSidebar and autoHeader are both enabled, for each link in _sidebar.md, prepend a header to the page before converting it to HTML — but only if the page does not already contain an H1 heading.

For more details, see #78.

window.$docsify = {
  loadSidebar: true,
  autoHeader: true,
};

basePath

Type: String

Base path of the website. You can set it to another directory or another domain name.

window.$docsify = {
  basePath: '/path/',

  // Load the files from another site
  basePath: 'https://docsify.js.org/',

  // Even can load files from other repo
  basePath:
    'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/',
};

catchPluginErrors

Type: Boolean
Default: true

Determines if Docsify should handle uncaught synchronous plugin errors automatically. This can prevent plugin errors from affecting docsify's ability to properly render live site content.

cornerExternalLinkTarget

Type: String
Default: '_blank'

Target to open external link at the top right corner. Default '_blank' (new window/tab)

window.$docsify = {
  cornerExternalLinkTarget: '_self', // default: '_blank'
};

coverpage

Type: Boolean|String|String[]|Object
Default: false

Activate the cover feature. If true, it will load from _coverpage.md.

window.$docsify = {
  coverpage: true,

  // Custom file name
  coverpage: 'cover.md',

  // multiple covers
  coverpage: ['/', '/zh-cn/'],

  // multiple covers and custom file name
  coverpage: {
    '/': 'cover.md',
    '/zh-cn/': 'cover.md',
  },
};

el

Type: String
Default: '#app'

The DOM element to be mounted on initialization. It can be a CSS selector string or an actual HTMLElement.

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

executeScript

Type: Boolean
Default: null

Execute the script on the page. Only parses the first script tag (demo). If Vue is detected, this is true by default.

window.$docsify = {
  executeScript: true,
};

markdown

## This is test

<script>
  console.log(2333)
</script>

Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the external-script plugin.

ext

Type: String
Default: '.md'

Request file extension.

window.$docsify = {
  ext: '.md',
};

externalLinkRel

Type: String
Default: 'noopener'

Default 'noopener' (no opener) prevents the newly opened external page (when externalLinkTarget is '_blank') from having the ability to control our page. No rel is set when it's not '_blank'. See this post for more information about why you may want to use this option.

window.$docsify = {
  externalLinkRel: '', // default: 'noopener'
};

externalLinkTarget

Type: String
Default: '_blank'

Target to open external links inside the markdown. Default '_blank' (new window/tab)

window.$docsify = {
  externalLinkTarget: '_self', // default: '_blank'
};

fallbackLanguages

Type: Array<string>

List of languages that will fallback to the default language when a page is requested and it doesn't exist for the given locale.

Example:

try to fetch the page of /de/overview. If this page exists, it'll be displayed.
then try to fetch the default page /overview (depending on the default language). If this page exists, it'll be displayed.
then display the 404 page.

window.$docsify = {
  fallbackLanguages: ['fr', 'de'],
};

fallbackDefaultLanguage

Type: String
Default: ''

When a page is requested and it doesn't exist for the given locale, Docsify will fallback to the language specified by this option.

For example, in the scenario described above, if /de/overview does not exist and fallbackDefaultLanguage is configured as zh-cn, Docsify will fetch /zh-cn/overview instead of /overview.

window.$docsify = {
  fallbackLanguages: ['fr', 'de'],
  fallbackDefaultLanguage: 'zh-cn', // default: ''
};

formatUpdated

Type: String|Function

We can display the file update date through {docsify-updated} variable. And format it by formatUpdated.
See https://github.com/lukeed/tinydate#patterns

window.$docsify = {
  formatUpdated: '{MM}/{DD} {HH}:{mm}',

  formatUpdated(time) {
    // ...

    return time;
  },
};

pageTitleFormatter

Type: Function
Default: null

Optional function to customize how the site name is used when composing the document title. If provided, Docsify will call this function with the configured name (which may contain HTML) and use the returned string as the title portion for the site name — Docsify will not automatically strip HTML or otherwise modify the value. If not provided, Docsify falls back to the default behavior of stripping HTML tags from name.

Basic example — strip HTML and trim (equivalent to Docsify's default behavior):

window.$docsify = {
  name: 'My Site',
  pageTitleFormatter(name) {
    return name ? name.replace(/<[^>]+>/g, '').trim() : '';
  },
};

hideSidebar

Type : Boolean
Default: false

This option will completely hide your sidebar and won't render any content on the side.

window.$docsify = {
  hideSidebar: true,
};

homepage

Type: String
Default: 'README.md'

README.md in your docs folder will be treated as the homepage for your website, but sometimes you may need to serve another file as your homepage.

window.$docsify = {
  // Change to /home.md
  homepage: 'home.md',

  // Or use the readme in your repo
  homepage:
    'https://raw.githubusercontent.com/docsifyjs/docsify/main/README.md',
};

keyBindings

Type: Boolean|Object
Default: Object
- \ Toggle the sidebar menu
- / Focus on search field. Also supports alt / ctrl + k.

Binds key combination(s) to a custom callback function.

Key bindings are defined as case insensitive string values separated by +. Modifier key values include alt, ctrl, meta, and shift. Non-modifier key values should match the keyboard event's key or code value.

The callback function receive a keydown event as an argument.

[!IMPORTANT] Let site visitors know your custom key bindings are available! If a binding is associated with a DOM element, consider inserting a <kbd> element as a visual cue (e.g., alt + a) or adding title and aria-keyshortcuts attributes for hover/focus hints.

window.$docsify = {
  keyBindings: {
    // Custom key binding
    myCustomBinding: {
      bindings: ['alt+a', 'shift+a'],
      callback(event) {
        alert('Hello, World!');
      },
    },
  },
};

Key bindings can be disabled entirely or individually by setting the binding configuration to false.

window.$docsify = {
  // Disable all key bindings
  keyBindings: false,
};

window.$docsify = {
  keyBindings: {
    // Disable individual key bindings
    focusSearch: false,
    toggleSidebar: false,
  },
};

loadNavbar

Type: Boolean|String
Default: false

Loads navbar from the Markdown file _navbar.md if true, else loads it from the path specified.

window.$docsify = {
  // load from _navbar.md
  loadNavbar: true,

  // load from nav.md
  loadNavbar: 'nav.md',
};

loadSidebar

Type: Boolean|String
Default: false

Loads sidebar from the Markdown file _sidebar.md if true, else loads it from the path specified.

window.$docsify = {
  // load from _sidebar.md
  loadSidebar: true,

  // load from summary.md
  loadSidebar: 'summary.md',
};

logo

Type: String

Website logo as it appears in the sidebar. You can resize it using CSS.

[!IMPORTANT] Logo will only be visible if name prop is also set. See name configuration.

window.$docsify = {
  logo: '/_media/icon.svg',
};

markdown

Type: Function

See Markdown configuration.

window.$docsify = {
  // object
  markdown: {
    smartypants: true,
    renderer: {
      link() {
        // ...
      },
    },
  },

  // function
  markdown(marked, renderer) {
    // ...
    return marked;
  },
};

maxLevel

Type: Number
Default: 6

Maximum Table of content level.

window.$docsify = {
  maxLevel: 4,
};

mergeNavbar

Type: Boolean
Default: false

Navbar will be merged with the sidebar on smaller screens.

window.$docsify = {
  mergeNavbar: true,
};

name

Type: Boolean|String

Website name as it appears in the sidebar.

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

The name field can also contain custom HTML for easier customization:

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

If true, the website name will be inferred from the document's <title> tag.

window.$docsify = {
  name: true,
};

If false or empty, no name will be displayed.

window.$docsify = {
  name: false,
};

nameLink

Type: String
Default: 'window.location.pathname'

The URL that the website name links to.

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

  // For each route
  nameLink: {
    '/zh-cn/': '#/zh-cn/',
    '/': '#/',
  },
};

nativeEmoji

Type: Boolean
Default: false

Render emoji shorthand codes using GitHub-style emoji images or native emoji characters.

window.$docsify = {
  nativeEmoji: true,
};

markdown

:smile:
:partying_face:
:joy:
:+1:
:-1:

GitHub-style images when false:

Native characters when true:

😄︎ 🥳︎ 😂︎ 👍︎ 👎︎

To render shorthand codes as text, replace : characters with the &colon; HTML entity.

markdown

&colon;100&colon;

:100:

noCompileLinks

Type: Array<string>

Sometimes we do not want docsify to handle our links. See #203. We can skip compiling of certain links by specifying an array of strings. Each string is converted into to a regular expression (RegExp) and the whole href of a link is matched against it.

window.$docsify = {
  noCompileLinks: ['/foo', '/bar/.*'],
};

noEmoji

Type: Boolean
Default: false

Disabled emoji parsing and render all emoji shorthand as text.

window.$docsify = {
  noEmoji: true,
};

markdown

:100:

:100:

To disable emoji parsing of individual shorthand codes, replace : characters with the &colon; HTML entity.

markdown

:100:

&colon;100&colon;

:100:

notFoundPage

Type: Boolean|String|Object
Default: false

Display default "404 - Not Found" message:

window.$docsify = {
  notFoundPage: false,
};

Load the _404.md file:

window.$docsify = {
  notFoundPage: true,
};

Load the customized path of the 404 page:

window.$docsify = {
  notFoundPage: 'my404.md',
};

Load the right 404 page according to the localization:

window.$docsify = {
  notFoundPage: {
    '/': '_404.md',
    '/de': 'de/_404.md',
  },
};

Note: The options for fallbackLanguages don't work with the notFoundPage options.

onlyCover

Type: Boolean
Default: false

Only coverpage is loaded when visiting the home page.

window.$docsify = {
  onlyCover: false,
};

plugins

See Plugins.

relativePath

Type: Boolean
Default: false

If true, links are relative to the current context.

For example, the directory structure is as follows:

text

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        ├── guide.md
        └── config
            └── example.md

With relative path enabled and current URL http://domain.com/zh-cn/README, given links will resolve to:

text

guide.md              => http://domain.com/zh-cn/guide
config/example.md     => http://domain.com/zh-cn/config/example
../README.md          => http://domain.com/README
/README.md            => http://domain.com/README

window.$docsify = {
  // Relative path enabled
  relativePath: true,

  // Relative path disabled (default value)
  relativePath: false,
};

repo

Type: String

Configure the repository url, or a string of username/repo, to add the GitHub Corner widget in the top right corner of the site.

window.$docsify = {
  repo: 'docsifyjs/docsify',
  // or
  repo: 'https://github.com/docsifyjs/docsify/',
};

If undefined or empty, no GitHub corner will be displayed.

requestHeaders

Type: Object

Set the request resource headers.

window.$docsify = {
  requestHeaders: {
    'x-token': 'xxx',
  },
};

Such as setting the cache

window.$docsify = {
  requestHeaders: {
    'cache-control': 'max-age=600',
  },
};

routerMode

Configure the URL format that the paths of your site will use.

Type: String
Default: 'hash'

window.$docsify = {
  routerMode: 'history', // default: 'hash'
};

For statically-deployed sites (f.e. on GitHub Pages) hash-based routing is
simpler to set up. For websites that can re-write URLs, the history-based format
is better (especially for search-engine optimization, hash-based routing is not
so search-engine friendly)

Hash-based routing means all URL paths will be prefixed with /#/ in the
address bar. This is a trick that allows the site to load /index.html, then it
uses the path that follows the # to determine what markdown files to load. For
example, a complete hash-based URL may look like this:
https://example.com/#/path/to/page. The browser will actually load
https://example.com (assuming your static server serves
index.html by default, as most do), and then the Docsify JavaScript code will
look at the /#/... and determine the markdown file to load and render.
Additionally, when clicking on a link, the Docsify router will change the
content after the hash dynamically. The value of location.pathname will still be
/ no matter what. The parts of a hash path are not sent to the server when
visiting such a URL in a browser.

On the other hand, history-based routing means the Docsify JavaScript will use
the History API
to dynamically change the URL without using a #. This means that all URLs will
be considered "real" by search engines, and the full path will be sent to the
server when visiting the URL in your browser. For example, a URL may look like
https://example.com/path/to/page. The browser will try to load that full URL
directly from the server, not just https://example.com. The upside of this is
that these types of URLs are much more friendly for search engines, and can be
indexed (yay!). The downside, however, is that your server, or the place where
you host your site files, has to be able to handle these URLs. Various static
website hosting services allow "rewrite rules" to be configured, such that a
server can be configured to always send back /index.html no matter what path
is visited. The value of location.pathname will show /path/to/page, because
it was actually sent to the server.

TLDR: start with hash routing (the default). If you feel adventurous, learn
how to configure a server, then switch to history mode for better experience
without the # in the URL and SEO optimization.

Note If you use routerMode: 'history', you may want to add an
alias to make your _sidebar.md and _navbar.md files always be
loaded no matter which path is being visited.
js
window.$docsify = {
  routerMode: 'history',
  alias: {
    '/.*/_sidebar.md': '/_sidebar.md',
    '/.*/_navbar.md': '/_navbar.md',
  },
};

routes

Type: Object

Define "virtual" routes that can provide content dynamically. A route is a map between the expected path, to either a string or a function. If the mapped value is a string, it is treated as markdown and parsed accordingly. If it is a function, it is expected to return markdown content.

A route function receives up to three parameters:

route - the path of the route that was requested (e.g. /bar/baz)
matched - the RegExpMatchArray that was matched by the route (e.g. for /bar/(.+), you get ['/bar/baz', 'baz'])
next - this is a callback that you may call when your route function is async

Do note that order matters! Routes are matched the same order you declare them in, which means that in cases where you have overlapping routes, you might want to list the more specific ones first.

window.$docsify = {
  routes: {
    // Basic match w/ return string
    '/foo': '# Custom Markdown',

    // RegEx match w/ synchronous function
    '/bar/(.*)'(route, matched) {
      return '# Custom Markdown';
    },

    // RegEx match w/ asynchronous function
    '/baz/(.*)'(route, matched, next) {
      fetch('/api/users?id=12345')
        .then(response => {
          next('# Custom Markdown');
        })
        .catch(err => {
          // Handle error...
        });
    },
  },
};

Other than strings, route functions can return a falsy value (null \ undefined) to indicate that they ignore the current request:

window.$docsify = {
  routes: {
    // accepts everything other than dogs (synchronous)
    '/pets/(.+)'(route, matched) {
      if (matched[0] === 'dogs') {
        return null;
      } else {
        return 'I like all pets but dogs';
      }
    }

    // accepts everything other than cats (asynchronous)
    '/pets/(.*)'(route, matched, next) {
      if (matched[0] === 'cats') {
        next();
      } else {
        // Async task(s)...
        next('I like all pets but cats');
      }
    }
  }
}

Finally, if you have a specific path that has a real markdown file (and therefore should not be matched by your route), you can opt it out by returning an explicit false value:

window.$docsify = {
  routes: {
    // if you look up /pets/cats, docsify will skip all routes and look for "pets/cats.md"
    '/pets/cats'(route, matched) {
      return false;
    }

    // but any other pet should generate dynamic content right here
    '/pets/(.+)'(route, matched) {
      const pet = matched[0];
      return `your pet is ${pet} (but not a cat)`;
    }
  }
}

skipLink

Type: Boolean|String|Object
Default: 'Skip to main content'

Determines if/how the site's skip navigation link will be rendered.

// Render skip link for all routes
window.$docsify = {
  skipLink: 'Skip to content',
};

// Render localized skip links based on route paths
window.$docsify = {
  skipLink: {
    '/es/': 'Saltar al contenido principal',
    '/de-de/': 'Ga naar de hoofdinhoud',
    '/ru-ru/': 'Перейти к основному содержанию',
    '/zh-cn/': '跳到主要内容',
  },
};

// Do not render skip link
window.$docsify = {
  skipLink: false,
};

// Use default
window.$docsify = {
  skipLink: true, // "Skip to main content"
};

subMaxLevel

Type: Number
Default: 0

Add table of contents (TOC) in custom sidebar.

window.$docsify = {
  subMaxLevel: 2,
};

If you have a link to the homepage in the sidebar and want it to be shown as active when accessing the root url, make sure to update your sidebar accordingly:

markdown

- Sidebar
  - [Home](/)
  - [Another page](another.md)

For more details, see #1131.

themeColor ⚠️ :id=themecolor

[!IMPORTANT] Deprecated as of v5. Use the --theme-color theme property to customize your theme color.

Type: String

Customize the theme color.

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

topMargin ⚠️ :id=topmargin

[!IMPORTANT] Deprecated as of v5. Use the --scroll-padding-top theme property to specify a scroll margin when using a sticky navbar.

Type: Number|String
Default: 0

Adds scroll padding to the top of the viewport. This is useful when you have added a sticky or "fixed" element and would like auto scrolling to align with the bottom of your element.

window.$docsify = {
  topMargin: 90, // 90, '90px', '2rem', etc.
};

vueComponents

Type: Object

Creates and registers global Vue. Components are specified using the component name as the key with an object containing Vue options as the value. Component data is unique for each instance and will not persist as users navigate the site.

window.$docsify = {
  vueComponents: {
    'button-counter': {
      template: `
        
          You clicked me {{ count }} times
        
      `,
      data() {
        return {
          count: 0,
        };
      },
    },
  },
};

markdown

vueGlobalOptions

Type: Object

Specifies global Vue options for use with Vue content not explicitly mounted with vueMounts, vueComponents, or a markdown script. Changes to global data will persist and be reflected anywhere global references are used.

window.$docsify = {
  vueGlobalOptions: {
    data() {
      return {
        count: 0,
      };
    },
  },
};

markdown

-
  {{ count }}
  +

text

-
{{ count }}
+

vueMounts

Type: Object

Specifies DOM elements to mount as Vue instances and their associated options. Mount elements are specified using a CSS selector as the key with an object containing Vue options as their value. Docsify will mount the first matching element in the main content area each time a new page is loaded. Mount element data is unique for each instance and will not persist as users navigate the site.

window.$docsify = {
  vueMounts: {
    '#counter': {
      data() {
        return {
          count: 0,
        };
      },
    },
  },
};

markdown

-
  {{ count }}
  +

- {{ count }} +

File: docs/cover.md

Cover

Activate the cover feature by setting coverpage to true. See coverpage configuration.

Basic usage

Set coverpage to true, and create a _coverpage.md:

window.$docsify = {
  coverpage: true,
};

markdown

# docsify

> A magical documentation site generator

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

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

Customization

The cover page can be customized using theme properties:

css

:root {
  --cover-bg         : url('path/to/image.png');
  --cover-bg-overlay : rgba(0, 0, 0, 0.5);
  --cover-color      : #fff;
  --cover-title-color: var(--theme-color);
  --cover-title-font : 600 var(--font-size-xxxl) var(--font-family);
}

Alternatively, a background color or image can be specified in the cover page markdown.

markdown

Coverpage as homepage

Normally, the coverpage and the homepage appear at the same time. Of course, you can also separate the coverpage by onlyCover option.

Multiple covers

If your docs site is in more than one language, it may be useful to set multiple covers.

For example, your docs structure is like this

text

.
└── docs
    ├── README.md
    ├── guide.md
    ├── _coverpage.md
    └── zh-cn
        ├── README.md
        └── guide.md
        └── _coverpage.md

Now, you can set

window.$docsify = {
  coverpage: ['/', '/zh-cn/'],
};

Or a special file name

window.$docsify = {
  coverpage: {
    '/': 'cover.md',
    '/zh-cn/': 'cover.md',
  },
};

Docker & Self-Hosted Deployment Verified OCI

File: README.md Copy Chapter

Features Copy Chapter

Quick Start Copy Chapter

Showcase Copy Chapter

Links Copy Chapter

Contributing Copy Chapter

Backers Copy Chapter

Sponsors Copy Chapter

Contributors Copy Chapter

License Copy Chapter

File: docs/_media/example-with-yaml.md Copy Chapter

author: John Smith date: 2020-1-1 Copy Chapter

File: docs/_coverpage.md Copy Chapter

docsify 5.0.0 :id=docsify

File: docs/_navbar.md Copy Chapter

File: docs/_sidebar.md Copy Chapter

File: docs/adding-pages.md Copy Chapter

Adding pages

Sidebar Copy Chapter

Nested Sidebars Copy Chapter

Set Page Titles from Sidebar Selection Copy Chapter

Table of Contents Copy Chapter

Ignoring Subheaders Copy Chapter

File: docs/cdn.md Copy Chapter

CDN

Specifying versions Copy Chapter

Latest "major" version Copy Chapter

Specific version Copy Chapter

File: docs/configuration.md Copy Chapter

Configuration

alias Copy Chapter

auto2top Copy Chapter

autoHeader Copy Chapter

basePath Copy Chapter

catchPluginErrors Copy Chapter

cornerExternalLinkTarget Copy Chapter

coverpage Copy Chapter

el Copy Chapter

executeScript Copy Chapter

ext Copy Chapter

externalLinkRel Copy Chapter

externalLinkTarget Copy Chapter

fallbackLanguages Copy Chapter

fallbackDefaultLanguage Copy Chapter

formatUpdated Copy Chapter

pageTitleFormatter Copy Chapter

hideSidebar Copy Chapter

homepage Copy Chapter

keyBindings Copy Chapter

loadNavbar Copy Chapter

loadSidebar Copy Chapter

logo Copy Chapter

markdown Copy Chapter

maxLevel Copy Chapter

mergeNavbar Copy Chapter

name Copy Chapter

nameLink Copy Chapter

nativeEmoji Copy Chapter

noCompileLinks Copy Chapter

noEmoji Copy Chapter

notFoundPage Copy Chapter

onlyCover Copy Chapter

plugins Copy Chapter

relativePath Copy Chapter

repo Copy Chapter

requestHeaders Copy Chapter

routerMode Copy Chapter

routes Copy Chapter

skipLink Copy Chapter

subMaxLevel Copy Chapter

themeColor ⚠️ :id=themecolor Copy Chapter

topMargin ⚠️ :id=topmargin Copy Chapter

vueComponents Copy Chapter

vueGlobalOptions Copy Chapter

vueMounts Copy Chapter

File: docs/cover.md Copy Chapter

Cover

Basic usage Copy Chapter

Customization Copy Chapter

File: README.md

Features

Quick Start

Showcase

Links

Contributing

Backers

Sponsors

Contributors

License

File: docs/_media/example-with-yaml.md

author: John Smith date: 2020-1-1

File: docs/_coverpage.md

File: docs/_navbar.md

File: docs/_sidebar.md

File: docs/adding-pages.md

Sidebar

Nested Sidebars

Set Page Titles from Sidebar Selection

Table of Contents

Ignoring Subheaders

File: docs/cdn.md

Specifying versions

Latest "major" version

Specific version

File: docs/configuration.md

alias

auto2top

autoHeader

basePath

catchPluginErrors

cornerExternalLinkTarget

coverpage

el

executeScript

ext

externalLinkRel

externalLinkTarget

fallbackLanguages

fallbackDefaultLanguage

formatUpdated

pageTitleFormatter

hideSidebar

homepage

keyBindings

loadNavbar

loadSidebar

logo

markdown

maxLevel

mergeNavbar

name

nameLink

nativeEmoji

noCompileLinks

noEmoji

notFoundPage

onlyCover

plugins

relativePath

repo

requestHeaders

routerMode

routes

skipLink

subMaxLevel

themeColor ⚠️ :id=themecolor

topMargin ⚠️ :id=topmargin

vueComponents

vueGlobalOptions

vueMounts

File: docs/cover.md

Basic usage

Customization

Coverpage as homepage

Multiple covers