live-markd

📝Github Favorite Markdown(gfm) preview with live rendering & location and highlight changed block.

Table of Contents

• Installation
• Usage
• API
• How it works?
• Related
• Contributing
• Authors
• License

Installation

npm install live-markd -g

live-markd .

Usage

Standalone

const liveMarkd = require('live-markd')

// Returns express app instance listened port 8080
const app = liveMarkd('path/to/dir', {
  port: 8080,
  baseUrl: '/www'
})

Use with express

const app = require('express')()
const liveMarkd = require('live-markd')

const middleware = liveMarkd('path/to/dir', {
  heartBeatDelay: 4 * 1000, // 4s
  gssOptions: {}
})

app.use(middleware)
// or
app.use('/base-url', middleware)

CLI

npm i live-markd -g
live-markd <path>

API

liveMarkd(root [, options])

root

The markdown files' root folder or exact file.

• Type: string

Options

port

The server's port

• Type: number

baseUrl

The server's baseUrl (only works on port is assigned)

• Type: string

heartBeatDelay

The heartbeat detection's interval millisecond

• Type: number
• Default: 10 * 1000

gssOptions

Except port, basePath, rest options extends github-similar-server

templateParameters

NOTE: Expect preset parameters from github-similar-server

live-markd has injected follow parameters

name	description
baseUrl	the base url from app.use('/baseUrl', lived(...))

markdownTemplate

The path of markdown's template, It's useful for customizing your suitable markdown style.

• Type: string
• Default: ./dist/template.html

How it works?

Data Flow

Fs Watcher -> Event Stream -> Client
                   |
   markdown diff   |   heartbeat & data
                   |
      [ Server ]   |   [ Browser ]

Markdown Diff

I use remark for treating markdown text as markdown abstract syntax tree(MDAST), then new MDAST comparing with old one.

For example

• old.md

# hi
world

• new.md

# hi
world!

• MDAST of old.md

{
  type: 'root',
  children: [
    {
      type: 'heading',
      depth: 1,
      children: [{
        type: 'paragraph',
        children: [{ type: 'text', value: 'world' }]
      }]
    }
  ]
}

• MDAST of new.md

{
  type: 'root',
  children: [
    {
      type: 'heading',
      depth: 1,
      children: [{
        type: 'paragraph',
        // This node is different with `old.md`
        children: [{ type: 'text', value: 'world!' }]
      }]
    }
  ]
}

Related

• github-similar-server - A github similar static server with a markdown renderer.
• detect-one-changed - Detect first changed html and markdown between old text and new one.

Contributing

• Fork it!
• Create your new branch:
  git checkout -b feature-new or git checkout -b fix-which-bug
• Start your magic work now
• Make sure npm test passes
• Commit your changes:
  git commit -am 'feat: some description (close #123)' or git commit -am 'fix: some description (fix #123)'
• Push to the branch: git push
• Submit a pull request :)

Authors

This library is written and maintained by imcuttle, [email protected].

License

MIT - imcuttle 🐟