Skip to content

Latest commit

 

History

History
618 lines (444 loc) · 11 KB

configuration.md

File metadata and controls

618 lines (444 loc) · 11 KB
Raw

Configuration

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

<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:

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

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',
};

repo

  • Type: String
  • Default: null

Configure the repository url, or a string of username/repo can 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/',
};

maxLevel

  • Type: Number
  • Default: 6

Maximum Table of content level.

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

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',
};

hideSidebar

  • Type : Boolean
  • Default: true

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

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

subMaxLevel

  • Type: Number
  • Default: 0

Add table of contents (TOC) in custom sidebar.

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

auto2top

  • Type: Boolean
  • Default: false

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

window.$docsify = {
  auto2top: 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/master/README.md',
};

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:

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

For more details, see #1131.

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/',
};

relativePath

  • Type: Boolean
  • Default: false

If true, links are relative to the current context.

For example, the directory structure is as follows:

.
└── 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:

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,
};

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',

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

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

logo

  • Type: String

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

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

name

  • Type: 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: '<span>docsify</span>',
};

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/',
    '/': '/',
  },
};

markdown

  • Type: Function

See Markdown configuration.

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

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

themeColor

  • Type: String

Customize the theme color. Use CSS3 variables feature and polyfill in old browser.

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

alias

  • Type: Object

Set the route alias. You can freely manage routing rules. Supports RegExp.

window.$docsify = {
  alias: {
    '/foo/(+*)': '/bar/$1', // supports regexp
    '/zh-cn/changelog': '/changelog',
    '/changelog':
      'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
    '/.*/_sidebar.md': '/_sidebar.md', // See #301
  },
};

autoHeader

  • type: Boolean

If loadSidebar and autoHeader are both enabled, for each link in _sidebar.md, prepend a header to the page before converting it to HTML. Compare #78.

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

executeScript

  • type: Boolean

Execute the script on the page. Only parse the first script tag(demo). If Vue is present, it is turned on by default.

window.$docsify = {
  executeScript: true,
};
## 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.

noEmoji

  • type: Boolean

Disabled emoji parse.

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

?> If this options is false but you dont want to emojify some specific colons , Refer this

mergeNavbar

  • type: Boolean

Navbar will be merged with the sidebar on smaller screens.

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

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: function(time) {
    // ...

    return time;
  },
};

externalLinkTarget

  • type: String
  • default: _blank

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

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

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'
};

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'
};

routerMode

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

noCompileLinks

  • type: Array

Sometimes we do not want docsify to handle our links. See #203

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

onlyCover

  • type: Boolean

Only coverpage is loaded when visiting the home page.

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

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',
  },
};

ext

  • type: String

Request file extension.

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

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

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'],
};

notFoundPage

  • type: Boolean | String | Object

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 localisation:

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

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

topMargin

  • type: Number
  • default: 0

Adds a space on top when scrolling content page to reach the selected section. This is useful in case you have a sticky-header layout and you want to align anchors to the end of your header.

window.$docsify = {
  topMargin: 90, // default: 0
};