kokk

A beautiful way to create a documentation from markdown, and insert a vue component into the doc as well.

  • kokk

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
kokk
5401.0.65 years ago5 years agoMinified + gzip package size for kokk in KB

Readme

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