kokk

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

luyilin

Vue

KOKK

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

minemine.cc · GitHub @luyilin · Twitter @luyilin12