docsifyjs / docsify

🃏 A magical documentation site generator.

A magical documentation site generator.

Gold Sponsor via Open Collective

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
• Support embedded files

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.

Links

• Documentation
• Docsify CLI (Command Line Interface)
• CDN: UNPKG | jsDelivr | cdnjs
• develop branch preview
• Awesome docsify
• Community chat

Contributing

See CONTRIBUTING.md.

Backers

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

Sponsors

Thank you for supporting this project！:heart: [Become a sponsor]

Contributors

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

License

MIT

Special Thanks

A preview of Docsify's PR and develop branch is Powered by

docsify's Issues

Roadmap for 1.0

• hash router (as a plugin) #2
• new theme https://github.com/egoist/hack
• prev/next button
• Improved scrolling on mobile
• new theme yoga.css https://facebook.github.io/yoga/docs/margin-padding-border/
• more CDNs

想了解一下docsify怎么生成静态页面？

通过docsify serve来启动服务。

那怎么让服务在后台运行？

我一开始想到的是用PM2，但试了一下无法集成。

像gitbook，它有一个gitbook build的命令，来生成_books目录，然后nginx指向它里面的index.html，就能跑起来访问了。

所以我想问docsify有没有这样的方法？还是要怎么做？看了一下命令，目前只支持：

• init
• serve

Coverpage broken

Cover page seems broken with your last release :( (see https://docsify.js.org/).

[bug] No horizontal scroll for code block on a mobile browser

At least on Firefox for Android... Didn't test on other browsers/mobile platforms, but people on v2ex reported this too.

Load page dynamically

For multiple-pages feature, I think you can replace the page directly and use history API or something alike to make it more smooth.

Auto-expand sidebar

What do I need to do to make the titles in sidebar auto expand when clicked, like https://docsify.js.org? 😄

Search on a mobile browser

Glad to see the search plugin! 👍
But there is a bug when I test it on a mobile browser (at least on Firefox for Android). When I click on the search bar, the sidebar will hide itself...

Another problem is that data-auto2top has no effect on a mobile browser.

Why use 404.html instead of index.html

I try rename 404.html to index.html, it works well, see: http://dplayer.js.org/docs/

Using 404 has two defect:

• Can't put docs to second-level directory
• Not SEO friendly

能否提供 markdownParser 接口，我希望在浏览器编译 jsx less

markrun('````js\nconsole.log(1)\n````',{template:''})

代码运行结果

<pre>console.log(1)</pre>
<script>console.log(1)</script>

如果能提供 markdownParser 接口，我就可以利用 markrun 在浏览器编译 jsx less

浏览器运行示例
github:markrun

<hr> support

Hey,

Thanks for bringing Docsify, it's awesome! I just noticed it lacks of <hr> styling, could you make that possible?

---

Here the Markdown horizontal rule specs.

The first menu on _sidebar.md cannot be clicked

For example:

[Home](/)
[Usage](/usage)

Home cannot be clicked.

Move external font css

For the first line in cdn/path/to/vue.css:

@import url('https://fonts.googleapis.com/css?family=Roboto+Mono|Source+Sans+Pro:300,400,600');

Maybe move the style to 404.html to make it customizable, or any better idea?

Hover over a heading to show an anchor icon and click it to copy the link

Like this:

Chinese anchors cannot be jumped to

For example, click the side bar item #问题反馈 on https://docs.snipaste.com/zh-cn, the page cannot jump to the corresponding position, and the console reports:

docsify.min.js:1 Uncaught DOMException: Failed to execute 'querySelector' on 'Document': '#%E8%B7%A8%E5%B9%B3%E5%8F%B0%E6%94%AF%E6%8C%81' is not a valid selector.(…)

I don't if this is a bug, or I should write it in another way?

A way to do search

Needs a way to do search in sidebar, like Docute. One options is something like http://lunrjs.com

即便翻墙了也打不开https://unpkg.com/docsify/themes/*

mailto support

I tried [asdf](mailto:[email protected]) and [asdf]([email protected]), but both generate incorrect links.

Links not working

Links into a book page and into "aside" is not working.
You may watch this by url.

Latest version is used.

Support links to be opened in another tab

Sometimes we need some of the links to be opened in another browser tab, i.e. with target="_blank".

When MD files have no content or no title, search function will be crash

When MD files have no content or no title, like this：

The index in localSearch value is:

This undefined value make search function crash...

搜索功能localstorage的更新

貌似在设置完搜索功能之后，需要更新搜索文档列表的时候必须手动删除localstorage才行，建议加一个key保存之前搜索文档的paths，检测到paths更新的时候自动更新一下localstorage里面的index

Multi-language navbars

The top navbar and the newly supported sidebar seem to be static only, which is bad if we have pages for different languages while the titles of the navbar items can only have one language.

As to the top navbar, being static is fine if we arrange the items like "En, 中文".
However, if we arrange them like "Download, Language (En, 中文)", where the items in parentheses mean they are contained in a dropdown list. When we switched to the Chinese page, the English navbar will be undesirable.

Maybe we can offer a way to bind each page with its navbars?

For example, we have four navbars: nav-top-1, nav-top-2, nav-left-1, nav-left-2.
If a page does not explicitly specify its navbars, the defualt ones will be used for it. If a page says it wants nav-top-2 and nav-left-2, these two will be used.

But how do we bind a page with a navbar? Sorry I have little knowledge about css or javascript...

Another possible improvement may be to allow the user to write their custom sidebars using markdown, just like Github Wiki does. They put it in _Sidebar.md.

Sorry if I am asking for too much. 😅

希望支持markdown中文换行。

在markdown的语法中，只要是英文开头的一行，按下回车之后，解析出来的html也会换行；但如果是中文开头的话，按回车换行解析出来还是会在同一行。按两次回车才会开始下一段落。这也是很多markdown编辑器不好用的一个点：英文可以自由换行，但中文就不行，还美其名曰markdown本身语法就是这样。不知作者能不能支持这个换行功能呢？

路由问题

这个是我通过docsify-cli生成的基本的结构，按照文档上说的做多页面的形式，目录结构如下：

但是当我点击 guide的时候，url是localhost:3000/guide，但是页面为空白。通过控制台发现请求的路径是:localhost:3000/guide/README.md。所以把目录变成下面这样：

guide文件也是能正常访问的。为何和文档上说的不一样，是我的写法不对吗？？

Deploying on vps

Hi, as discussed in #7 , it's not SEO friendly to always return 404. From my understanding, it's due to the way github hosts the contents. Since I can also deploy the documention on my vps, I suppose there should be ways to avoid returning 404, is that right? If so, could you offer some instructions about it? Thanks!

Problem with subdirectory after enabling data-router

After upgrading to v1.0.1 and enabling data-router, the pages in the subdirectory seems broken, returning 404. See https://docs.snipaste.com/zh-cn/.
Are there any extra modifications I should make?

wrong slugify result for some heading situation

e.g http://magicdawn.ml/clean-code-javascript/#/

there are some md code like

## **Variables**
### Use meaningful and pronounceable variable names

GitHub renders like

<h2>
  <a id="user-content-variables" class="anchor" href="#variables" aria-hidden="true">
    <svg>...</svg>
  </a>
  <strong>Variables</strong
</h2>

And docsify renders

<h2 id="strongvariablesstrong">
  <a href="#/#strongvariablesstrong" data-id="strongvariablesstrong" class="anchor">
    <span>
      <strong>Variables</strong>
    </span>
  </a>
</h2>

cause

results

Manually anchor broken

Can directly use `/README.md` instead of copy to `/docs/README.md` ?

I think it is very good if use /README.md in the root dir. Now docsify init docs would copy it to /docs. It make me to maintain two README.md file. That is bad idea.

Emoji support

I'd put this on the low priority list, but I think it would be worth a look. Since the .md files we're writing support emoji, especially readme.md which is going to be read as often in the repo as it is on the docs site - it would probably make sense to also display those emoji as images on the docs site. Right now they're just raw codes like :smile:.

I think there's a few libraries out there that might help with this if you want one - imojify is one I found after a quick search.

我需要文档和代码实例在同一张页面，如何实现呢？

我的文档想用markdown写内容，同时里面有代码示例，需要写js、html、css。html和css没事，但是js在markdown中不能运行。我认为是markdown解析的时候就将script标签的脚本都忽略了。。。所以不能运行。但是我确实想找到一个办法来写这样的文档。不知道作者你有什么思路呢？我可以改造你和docute的代码也行，但是目前没思路，不知道怎么改。

Remove blank in the sidebar for headings linking to other pages

When I use

## Getting Started

### [Snip](/Getting-Started#snip)

an unwanted blank line appears in the side bar:

It corresponds to <a class="section-link" href="#snip"></a>, which I think should be removed.

---

Also, I am wondering if there is any way that I can hide certain headings in the content but keep them visible in the sidebar. The reason is that I have multiple pages and I would like to keep a consistent sidebar for all pages, while the content of each page stays clean and will not show the headings linking to other pages.

Roadmap

• cli tool
  • serve
  • build
• docsify.pack.js bundle package
• configuration file [maybe]

Styling <kbd> element

I currently style <kbd> by my custom css:

kbd {
    display: inline-block;
    padding: 3px 5px;
    margin-bottom : 3px;
    font-size: 12px !important;
    line-height: 12px;
    vertical-align: middle;
    border: solid 1px #ccc;
    border-radius: 3px;
}

Result:

But since keys are common to see in a documentation, it would be better to support it by default.

Arbitrary background color for cover page

Currently the background of cover page is generated randomly. In some cases, when put together, the generated color and the coloring of project's logo don't quite match. Any thoughts on letting users configure their own background colors?

Another thing, Math.floor(Math.random() * 255) makes it impossible for hue to be greater than 255, thus the background color may never be purple or pink. Is this on purpose?

Hope to offer dark theme

It is healthy for coder's eye if offer some theme like vscode or IntelliJ IDEA's Darcula theme.

some items in sidebar highlight incorrectly.

check https://docsify.js.org/#/cdn?id=other-cdn
click other-cdn, it won't be highlighted.

it is because sidebar highlight is computed from scroll position, but several headers in the last will never appear on top of viewport

能不能添加nav固定的功能

如题

Auto header for each page

Take docisfy as an example:

With loadSidebar enabled, in docs/_sidebar.md, we have:

- Getting started
 - [Quick start](/quickstart)
 - [Writing more pages](/more-pages)
 - [Custom navbar](/custom-navbar)
 - [Cover page](/cover)

...

The first line of /quickstart is # Quick start, and the first line of /custom-navbar is # Custom navbar, etc.
It would be great if we do not have to manually write these lines, since they can be inferred from the sidebar.

It has 3 advantages at least:

• Save a line in each subpage, of course.
• Whenever we want to change the header for a subpage, we only need to modify it in the sidebar, not both places. And the inconsistency can be avoided naturally.
  • For example, at the moment, docsify has Writing more pages for /more-pages in the sidebar, while the first line of /more-pages.md is More pages. Such inconsistency may not be desireable.
• Be consistent with the behavior of Github Wiki.
  • In Github Wiki, a page named Changelog, which is actually a file Changelog.md, will have the header 'Changelog' automatically. We do not have to add a line # Changelog in the content. See here for an example.
  • If this feature is implemented, we will be able to directly use Github Wiki for docsify. For example, the md file for the link above is 'https://raw.githubusercontent.com/wiki/liulex/Snipaste-Feedback/Changelog.md'. We can alias /Changelog to it. Then we can have a Github Wiki (for community edit) and a doscify generated site at the same time!

In case I haven't made myself clear, the logic of this feature (maybe named autoHeader) is:

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

For example, if [Quick start](/quickstart) is in _sidebar.md, we prepend a line # Quick start into /quickstart.md before we render /quickstart.md into html.

nav not work on github pages

[bug] Github repo link ineffective

data-repo="your/repo" has no effect for v0.5.0. The corner widget always links to https://github.com/true.

The sidebar "shakes" when the page is being scrolled on IE / Microsoft Edge

Only on IE / Microsoft Edge...

Strange dropdown list animation

Hi, I have just updated to v0.6 and found this strange animation:

Another thing is that the github corner widget is too large and has affected the navbar items:

Cover custom color only works for hex/name

You give an example of using a CSS linear-gradient as a custom background on the cover in #40 (comment). But this doesn't work for me, I can only get simple hex or name (green) values to work.

This line copied directly from your comment doesn't work when placed in cover.md:

![color](linear-gradient(to left bottom, #b3ffc8 0%, #eeffb3 100%))

Problems in page navigation

For example:

1. Open https://docs.snipaste.com/
2. Click 'Image Edit'
   • Problem 1: the page does not jump to #image-edit
3. Scroll the current page, then click 'Image Edit' again, no effects
4. But if we now click 'Snip' or 'Paste', the page jumps correctly
   • Problem 2: however, in the sidebar, the highlighted menu is still "Image Edit'
5. Then click on another top-level page in the sidebar, for exmaple, 'Advanced Configs'
   • Problem 3: the page is not scrolled to top

Links in coverpage's description

When using links in the coverpage's description (blockquote), they also appear as buttons, which certainly is unwanted:

只能是单页的？不能有其他页吗？

rt

Localization for search plugin

At the moment, we can only specify one placeholder for the search plugin, like "Type to search". However, when the user is on a Chinese page, it would be more friendly to use a translated placeholder, like "搜索...“.

I think we can bind the placeholder to the path, just like the sidebar. For example, we can support the following syntax:

window.$docsify = {
    search: {
      placeholder: {'/' : 'Type to search', '/zh-cn' : '搜索...'}
    }
  }

Cover page

Likes http://monterail.github.io/vue-multiselect/ , but we need only to write markdown 😜

Something wrong with TOC

You can see: hd.rdbcn.pw/#/channels

The structure of document like this:

# level 1
## sub level 1.1
### sub level 1.1.1
### sub level 1.1.2
#### sub level 1.1.2.1
#### sub level 1.1.2.2
## sub level 2.1
### sub level 2.1.1
### sub level 2.1.2
# level 3
# level 4

Anchor in sub-levels in TOC not working :(

There is some errors:

支持任意URL

能否支持任意URL，这样我就可以放在我自己的服务器上

比如：

docsify('https://raw.githubusercontent.com/myrepo/master/README.md')