kokk
v1.0.6
Published
A beautiful way to create a documentation from markdown, and insert a vue component into the doc as well.
Downloads
800
Readme
KOKK
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 --saveCDN: 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.
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