Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/imcuttle/live-markd
📝Github Favorite Markdown preview with live rendering & location and highlight changed block.
https://github.com/imcuttle/live-markd
gfm github live markdown preview
Last synced: about 1 month ago
JSON representation
📝Github Favorite Markdown preview with live rendering & location and highlight changed block.
- Host: GitHub
- URL: https://github.com/imcuttle/live-markd
- Owner: imcuttle
- License: mit
- Created: 2018-10-26T15:02:21.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-24T06:27:17.000Z (about 2 years ago)
- Last Synced: 2024-12-20T05:26:07.215Z (2 months ago)
- Topics: gfm, github, live, markdown, preview
- Language: JavaScript
- Homepage:
- Size: 3.12 MB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: License
Awesome Lists containing this project
README
# live-markd
[](https://travis-ci.org/imcuttle/live-markd)
[](https://codecov.io/github/imcuttle/live-markd?branch=master)
[](https://www.npmjs.com/package/live-markd)
[](https://www.npmjs.com/package/live-markd)
[](https://prettier.io/)
[](https://conventionalcommits.org)
> 📝Github Favorite Markdown([gfm](https://github.github.com/gfm/)) preview with live rendering & location and highlight changed block.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [How it works?](#how-it-works)
- [Related](#related)
- [Contributing](#contributing)
- [Authors](#authors)
- [License](#license)
## Installation
```bash
npm install live-markd -g
live-markd .
```
## Usage
#### Standalone
```javascript
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
```javascript
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
```
## 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](https://github.com/imcuttle/github-similar-server)**
###### `templateParameters`
**NOTE:** Expect [preset parameters](https://github.com/imcuttle/github-similar-server/blob/master/README.md#about-markdowntemplate) 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`](./dist/template.html)
## How it works?
### Data Flow
```text
Fs Watcher -> Event Stream -> Client
|
markdown diff | heartbeat & data
|
[ Server ] | [ Browser ]
```
### Markdown Diff
I use [remark](https://github.com/remarkjs/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](https://github.com/syntax-tree/mdast) of `old.md`
```javascript
{
type: 'root',
children: [
{
type: 'heading',
depth: 1,
children: [{
type: 'paragraph',
children: [{ type: 'text', value: 'world' }]
}]
}
]
}
```
- [MDAST](https://github.com/syntax-tree/mdast) of `new.md`
```javascript
{
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](https://github.com/imcuttle/github-similar-server) - A github similar static server with a markdown renderer.
- [detect-one-changed](https://github.com/imcuttle/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](https://github.com/imcuttle) 🐟