The easiest way to write beautiful docs.
Clone or download
Latest commit 1f44663 Mar 11, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs bump version Mar 11, 2018
src fix h4 size Mar 11, 2018
.editorconfig init Nov 30, 2017
.gitattributes init Nov 30, 2017
.gitignore clean up Nov 30, 2017
LICENSE init Nov 30, 2017
circle.yml init Nov 30, 2017
package.json v0.0.29 Mar 11, 2018
yarn.lock support highlighting lines Mar 11, 2018

README.md

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:

2017-12-01 1 22 20

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

hide-image

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>

Hightlight

Docup uses Prism.js to highlight code blocks, by default only a few languages are supported, namely: html css js markdown bash json, you can manually load Prism language components to support more languages, e.g. for Go programming language:

<script src="https://unpkg.com/@egojump/docup/dist/docup.js"></script>
<!-- Load languages after main Docup script -->
<script src="https://unpkg.com/prismjs/components/prism-go.js"></script>

Highlight specific lines

As you can see in the above section, the third line in the code block is highlighted with a background color, this is achieved by:

```html{2}
<div>
  This line will be highlighted!
</div>
```

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:

gh-pages enable

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.

description

Type: string

The description that is shown below the title.

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;
}
customFont

Type: string
Default: undefined

Use a custom font from Google Fonts, we will automatically inject corresponding <link> tag into head if this is set.

For example, try using Source Sans Pro or Open Sans here.

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.

License

MIT © EGOIST