Create a beautiful doc from a markdown file. You can insert a vue component into the doc as well.

55
2
Vue

KOKK

NPM version NPM downloads

DEMO

Here is another DEMO which insert a component into the doc, the source code is in examples/insertComponent.

A doc for vue-cute-rate which powered by kokk.

Introduction

KOKK is a tool that fetches a Markdown file and renders it as a beautiful one-page documentation.

More than this, you can insert a vue component into the doc. In this example, it use vue-juri to insert two demos of vue-cute-rate into the doc, seems cool, right? 😉

The design is inspired by Ant Design! I like the elegant way to display a documentation.

The name is inspired by Kokkoku 💃

Install

yarn add kokk --save

CDN: UNPKG | jsDelivr (available as window.Kokk)

Quick Start

Create an HTML file: index.html which will be be homepage of your documentation website:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0" />
  <title>My Awesome Doc</title>
</head>
<body>
  <div id="app"></div>
  <!-- Script -->
  <script src="https://unpkg.com/kokk@latest/dist/kokk.js"></script>
  <!-- Start app -->
  <script>
    const doc = new Kokk()
    doc.start('#app')
  </script>
</body>
</html>

Then populate a README.md file to the same directory where index.html is located.

Finally serve this directory as a static website:

E.g. node.js: npm i -g serve && serve ./docs

Guide

Where to add a vue component?

Write <!-- DEMO --> on where you want them to be in the main markdown file. Examples will be rendered here. Here is a simple example of main markdown file.

## Install

<!-- DEMO -->

## Options

How to add a vue component?

const doc = new Kokk()

doc.addComponent({
  order: 4,
  component: () => import('../components/Demo.vue')
})

doc.start('#app')

Hide content in documentation

If you want to display some part on GitHub while keeping it invisible in kokk, you can use following html comment marks:


<!-- hide-on-kokk-start -->

This part is not visible while viewing as a kokk website.

<!-- hide-on-kokk-stop -->

For example, you can see an image down below while viewing on GitHub.

hide-image

Show content in documentation

If you want to hide some part on GitHub while keeping it visible in kokk, you can use following html comment marks:

<!-- show-on-kokk
This part is not visible on github, as it's html comment :)
But it's visible on your kokk website.
All markdown features except html comments are supported here.
-->

If you’re on the kokk website, you can see an image down below.

API

Constructor

const doc = new Kokk(options)

Options

Property Description type Default
root The path of the markdown file. string ./
mainDoc The main markdown file. string README.md
titleClassname The custom classname of title. The title defaults to the value of h1 title in the main markdown file. string -
highlight Whether to highlight code blocks, you can supply a function to customize this, use prismjs to highlight code by default. boolean / function true
loadingColor The color of the loading component. string #7175b1

For root, in many cases you already have README.md in your repo, there is no need to populate another file at  ./, just use a markdown file from url directly, like this

const doc = new Kokk({
  root: 'https://raw.githubusercontent.com/luyilin/kokk/master/',
})

doc.addComponent(options)

Options

Property Description type Default
title The title of the example part. string Examples
order The order of the example part in the documentation, set this to implement the menu. number 3
component The vue component which you want to import function () => {}
showExpandIcon Show a expand svg or not. The option will be useful when you use vue-juri to show a list of demos 😄 boolean false

doc.start(target)

target

Type: string HTMLElement

The place to mount app to.

Author

KOKK © luyilin, released under the MIT License.

minemine.cc · GitHub @luyilin · Twitter @luyilin12