Docup

Introduction

Docup is a single JavaScript file that fetches Markdown file and renders it as a beautiful one-page documentation.

The idea is inspired by my another project (Docute) which in turn is inspired by Flatdoc. And the design is inspired by tj (TJ Holowaychuk)'s wonderful docs for Apex Up.

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>
  <!-- Stylesheet -->
  <link rel="stylesheet" href="https://unpkg.com/@egojump/docup/dist/docup.css">
</head>
<body>
  <div id="app"></div>
  <!-- Script -->
  <script src="https://unpkg.com/@egojump/docup/dist/docup.js"></script>
  <!-- Start app -->
  <script>
    var doc = new Docup()
    doc.start('#app')
  </script>
</body>
</html>

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

# My Project

## Introduction

How about this.

## Advanced

How about that.

Finally serve this directory as a static website:

node.js: npm i -g serve && serve ./docs
python: cd ./docs && python -m SimpleHTTPServer
golang: cd ./docs && caddy
...etc, you can use any static file server, for real.

Guide

Site Title

We use the value of h1 title as the site title.

Message Blocks

To highlight some messages in your documentation, use the following format to write a blockquote:

> __Alert__: This is a very dangerous action!

On GitHub it will be rendered as follows:

And with Docup it renders:

Alert: This is a very dangerous action!

We also support other message types which are:

> __Info__: This is a info!

<!-- -->

> __Warning__: This is a warning!

<!-- -->

> __Success__: This is ok!

<!-- -->

> __Note__: This is just a note!

Warning: Notice the  here, we use it to write multiple blockquotes in sequence without them being merged into one blockquote. It's unnecessary if you only have one blockquote.

And they look like:

Info: This is a info!

Warning: This is a warning!

Success: This is ok!

Note: This is just a note!

Hide specific content

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

<!-- hide-on-docup-start -->

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

<!-- hide-on-docup-stop -->

Warning: There should be newlines wrapping the starting and ending mark, like what you see above.

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

Show specific content

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

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

If you're on the Docup website, you can see an image down below.

Embeding

Embeding and run code snippets is easy if your provider supports iframe, like codesandbox.io:

<iframe 
  src="https://codesandbox.io/embed/vue" 
  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;" 
  sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin">
</iframe>

Deploy

GitHub Pages

Simply put all your files in docs folder on master branch, or root directory on the gh-pages branch.

Then enable it on repo's settings page:

Don't forget to add .nojekyll file to tell GitHub to treat it as a normal static website.

API

Constructor

const doc = new Docup(options)

options

title

Type: string

The title that is shown in the header. It defaults to the value of h1 title in your markdown file.

indexFile

Type: string
Default: README.md

root

Type: string
Default: ./

highlight

Type: boolean function
Default: true

Whether to highlight code blocks, you can supply a function to customize this:

function highlight(code, lang) {}

highlightFirstParagraph

Type: boolean
Default: false

Highlight the first paragraph after h2 titles. Basically this option enables following CSS:

h2 + p {
  font-size: 1.6rem;
  line-height: 1.6;
}

doc.start(target)

target

Type: string HTMLElement

The place to mount app to.

Roadmap

Browser support

I will add support for IE10+ very soon.

Prerender

Prerender index.html

Multi-route support

Maybe, maybe not.

hcysunyang / docup Goto Github PK

docup's Introduction