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

John Hildenbiddle 7cf1e7c27a Update Vue-related descriptions and links

2020-11-19 15:42:51 -06:00

14 KiB

Raw Blame History

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

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

  // multiple 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 don't 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'
};

crossOriginLinks

type: Array

When routerMode: 'history', you may face the cross-origin issues, See #1379. In Markdown content, there is a simple way to solve it, see extends Markdown syntax Cross-Origin link in helpers.

window.$docsify = {
  crossOriginLinks: ['https://example.com/cross-origin-link'],
};

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

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

vueComponents

type: Object

Creates and registers global Vue components. 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: `
        <button @click="count += 1">
          You clicked me {{ count }} times
        </button>
      `,
      data() {
        return {
          count: 0,
        };
      },
    },
  },
};

<button-counter></button-counter>

vueGlobalOptions

type: Object

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

<p>
  <button @click="count -= 1">-</button>
  {{ count }}
  <button @click="count += 1">+</button>
</p>

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

<div id="counter">
  <button @click="count -= 1">-</button>
  {{ count }}
  <button @click="count += 1">+</button>
</div>