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.

Usage

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.

Conventions

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!

Deploy

GitHub Pages

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

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

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.

clarksun/docup