egoist / docute

📚 Effortless documentation, done right.

ATTENTION: this project is no longer actively maintained (I still push some code once in a while), if you want to see improvements on this project, please consider sponsoring me.

Docute

Effortless documentation, done right.

Features

• No build process, website is generated on the fly.
• A simple yet elegant UI that is dedicated to documentation.
• Leveraging the power of Markdown and Vue.
• Extensible plugin system, plenty of official and community plugins.

Documentation

• v4 (latest) docs: https://docute.egoist.dev
• v3 (legacy) docs: https://docute3.egoist.dev

Resources

• Official Plugins
• Awesome Docute

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Author

Docute © EGOIST, Released under the MIT License.
Authored and maintained by EGOIST with help from contributors (list).

Website · GitHub @EGOIST · Twitter @localhost_5173

docute's Issues

Server-side rendering

docute can be used alone as single page app but what if it supports SSR? If you care about SEO then SSR is a big win!

The further plan is to support generating static html files at some point.

Maybe it will be the first docs generator that supports:

• single page app, build docs on the fly
• server-side rendering, you don't need to build the docs but also have it seo-friendly
• build to static files, just like traditional static website generator

如何添加侧边栏

文档中好像没有关于如何添加侧边栏的说明？

[bug] Warning CSS is above dropdown menu

The dropdown menu seems to be underneath tip/warning css

Provide an optimized version

we can bundle all vendor code in a single file:

• optimized/docute-vendor.js <- this will rarely change unless we add new dependencies
• optimized/docute-client.js

CSS does not change

Build a local search plugin

Using the plugin API for searching: https://docute.org/plugin-api#apienablesearchoptions

---

IssueHunt Summary

Backers (Total: $200.00)

• issuehunt ($200.00)

Submitted pull Requests

• #261 Build a local search plugin

---

Become a backer now!

Or submit a pull request to get the deposits!

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

---

IssueHunt has been backed by the following sponsors. Become a sponsor

Allow plugin to parse doc content

Maybe expose beforeParse and afterParse:

function myPlugin(ctx) {
  ctx.beforeParse(markdown) {
    return manipulateMarkdown(markdown)
  }
  ctx.afterParse(html) {
    return manipulateHtml(html)
  }
}

suggestion: redirect to the same page if I switch language

Now if I'm visiting the page: /plugins and switch language to zh-Hans, page will be redirected to home page: /zh-Hans/. But I wonder if page can be redirected to /zh-Hans/plugins?

Support history mode

If you're using github pages, you can use 404.html together with index.html to simulate a history-mode app (redirect 404.html to index.html), what we need to change is to make docute update location.hash instead query.id in history mode

Access Vue Variable on plugin

I want to create a plugin, but to create a plugin, I need to register a component first. Unfortunately I cannot create a Vue component because I can't access Vue variable from config.js where we usually init a plugin. The config.js is located before the docute js file.

Please help me on this.

[feature request] execute script tag inside markdown

因为一些原因需要在markdown里写一些js但是无法执行，这有什么办法解决么？（index.html里写没问题，但是需要在markdown里写。。）

Build to static html files

Just simply matching all markdown files, for example docute build docs -> glob.sync('docs/**/*.md') and we can get something like:

[ 'docs/cli.md',
  'docs/ja/cli.md',
  'docs/ja/plugins.md',
  'docs/ja/README.md',
  'docs/plugins.md',
  'docs/README.md',
  'docs/zh-Hans/cli.md',
  'docs/zh-Hans/plugins.md',
  'docs/zh-Hans/README.md',
  'docs/zh-Hant/cli.md',
  'docs/zh-Hant/plugins.md',
  'docs/zh-Hant/README.md' ]

and build to '.docute' folder, docs/cli.md => .docute/cli/index.html

with vue-server-renderer it should not be hard.

[bug] scrolling inspector of sidebar mismatches

As the screenshot shows, scrolling inspector of sidebar is somehow mismatching the scrollTop of document.

Icon/Logo design

It's nice to make a icon or a logo, could be used as favicon.ico or shown in such tool:

Add short-hand to set main color

the color for progress bar and links, titles etc is #4078c0, an option mainColor: '#xxxxxx' might be handy.

Support progressive web app

[draft] Adding progressive web app support:

self.$config = {
  pwa: true
}

And then put sw.js (serviceworker) to the path of your docs.

how to hide sidebar on individual pages?

like hide in home page. can I use front-matter in markdown file to turn it on and off? Thanks!

Optimization for wide screens

In current layouts, contents will take up as much space as they can. On my 1080p monitor, it's a bit hard to read text from leftmost to rightmost. What about adding a max-width property to contents and align them in the center?

Add "edit on github" icon in header

And set prefix by edit-on-github option:

self.$config = {
  // for example:
  'edit-on-github': 'https://github.com/egoist/docute/blob/master/docs'
}

doc: navbar => nav

---
navbar: chinese
---

=>

---
nav: chinese
---

It really took me long time to find out the error.

Cannot Put Remote URL On Navbar

Is there any way I can do this on config file?

nav: {
    default: [{
       title: 'Documentation', 
       path: 'https://raw.githubusercontent.com/ctrlplusb/react-universally/master/docs/NPMCommands.md'
     }]
  }

Where the path is remote URL instead of local markdown. I tried but it cannot load the markdown.

The readability of highlight.js is really bad

Sorry for bothering again 😂. As you can see from the screenshot below, the syntax highlight of highlight.js is really hard to read, it seems almost everything is black and thus messing up:

Since this is an internal module, I could not modify it 😢. Would you mind switching to the other plugins like the old Prism.js?

Search in docs

Currently there's no universal way to search a keyword in markdown files, the last option I can think of is to generate a json file for these files for searching 🤔 but um.. you need to generate each time after you updated the docs ...

Generate Epub and PDF

The last heading is unclickable

When you visit the page with query id like https://docute.js.org/#/?id=deploy-to-vps-12 , it will mark Deploy to GitHub as active heading instead of Deploy to VPS

I guess we need to update url query id to active id after scroll ended, as in the example it's deploy-to-github-11, since you can never scroll to deploy-to-vps-12, related to #9

[Bug] dropdown menu navigation doesn't work in iPad landscape mode

When viewing the docute documentation on a 9.7" iPad Pro in landscape mode, the dropdown navigation doesn't work. I'm only able to access the 'Languages' dropdown if I use Portrait mode with the pull-out menu.

suggestion: set default dropdown item

I need to set a dropdown like this

- All Components  `/components`
- Form Components `/components_form`
- layout Components `/components_layout`

when users click the dropdown, it goes to /components without selecting.
And when users select Form Component, the dropdown title should be changed to Form Components.

Now it seems impossible to do this.

Build a disqus plugin

Better 404 page

When the ajax call returns a 404 status code it renders the 404 page

Unable to scroll to the last heading

As you can see, no way to scroll to using nginx:

[suggestion] change the route of home page

After I added landing page, the route of home page will be locked in /#/home. It would be helpful if I can change the route of home like, hm, guide, since I am using it as Getting started page.

Convert id in link

For [Introduction](#introduction) we will get a link like <a href="#introduction" ... but it should be <a href="?id=introduction" in docute.

maybe just convert to <a jump-to-id="introduction"

How to add pagination?

docute is very cute 👻 . It is awesome documentation tool. but Where can I find pagination?

Support GFM task lists

eg:

- [x] done
- [ ] todo

need a little hack to marked

[question] Living component guide

Hi there, thanks to put this together, docute is really awesome.

I'd like to create a living component like style guide, showing different states of some components, also show some tabbed content, like preview and source code (maybe some markdown plugin to show tabs?).

Is this some how supported by docute? If so, what would be the best approach to author such style guide using docute?

Thanks!

Better mobile experience

Hide sidebar and add a breadcrumb icon in header to toggle it, we can also put the navbar in sidebar, just like how vuejs.org looks like.

Support markdown link context

If a link in markdown is relative path or absolute path, we can use context to change the url, this would be useful if you're loading external markdown file:

self.$config = {
  marked: {
    linkContext: 'https://raw.githubusercontent.com/user/repo/master'
  }
}

[feature request]cover/landing page support

Noticed that cover pages have been supported by docsify since a recent update (well, I don't know the exact version...). As most open source projects are serving an appealing landing page, I think it would be great if we could also create a cover or landing page for docute :)

Custom sidebar

some people may want to custom their sidebar with pages instead of using navbar.

we can allow this by:

self.$config = {
  sidebarNav: [
    // exactly same usage as `nav` but display in sidebar
    {title: 'About me', path: '/'}
  ]
}

And replace TOC with this.

Translations

New translations go to ./docs/$languages_code/

Expose some internal variables and methods

I can see the benefits if user can access router and vuex store or even Vue constructor:

window.docute = {}
docute.router = vueRouter
docute.store = vueStore
window.Vue = Vue

Support gitbook-like behavior

a gitbook mode, which means you can provide a summary.md to set the sidebar menu:

- [Get started](get-started.md)
- [Advanced](advanced.md)

Then we won't parse and set toc in the sidebar but instead use the custom menu, it's like the nav but moved to sidebar ^_^

put routers at left instead

目前的docute是只能把导航栏放在顶部，而左侧的导航栏只能导航一个MD文件的标题。

但是，有很多情况下，是MD文件较多，需要把路由放在左侧能更加方便（忽略MD页面内部导航）。比如：http://ionicframework.com/docs/

请问这种情况下，我该怎么使用docute？谢谢。

CLI tool in other languages

the docute-cli is just a scaffolding tool and a server with live reloading, it would be easy to implement in other languages, like golang.

The idea to make it in other languages is to enforce that you don't even need node.js installed for making docs, use the language you desire instead.

Global banner and footer

----------banner-----------
| parsed markdown content|
----------footer------------

Support more icons

• weibo
• zhihu
• facebook
• linkedin
• profile
• ...

Anyone is good at drawing svg icon? 😃

Scroll spy

Add active class to relevant sidebar item when scrolling

导出pdf和html，打包apk

这三个功能加上，就完美了。

Emoji support in markdown

new plugin request.

想了解一下关于搜索这一块

这个地址：https://docute.js.org/#/home

左上角有搜索框，想了解它的具体点实现？

比如说应该怎么配置，才能出来？

另外想了解的是如果是多个md的话，这个搜索，会不会针对所有的md进行搜索，还是针对当前的md进行搜索？

Multiple navbar

There's such use case:

A navbar for English doc /#/, but use another navbar for Chinese doc /#/zh-cn/*

So we can allow this by setting front-matter in your markdown file:

---
navbar: chinese
---

And update your config.js to:

self.$config = {
  nav: {
    default: [{title: 'About', path: '/en/about'}],
    chinese: [{title: '关于', path: '/zh-cn/about'}]
  }
}