markserv

by markserv

markserv / markserv

🏁 serve markdown as html (GitHub style), index directories, live-reload as you edit

256 Stars 53 Forks Last release: Not found MIT License 299 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Markserv Logo

:checkered_flag: serve markdown as html (GitHub style), index directories, and live-reload as you edit

Gitter CHANGELOG Build Status Coverage Status All Contributors Npm Version XO code style Known Vulnerabilities

Markserv Demo

:sparkles: Features

  • Markdown content rendered as HTML
  • GitHub flavor CSS and Syntax Highlighting
  • Just in Time Templating: Markdown, HTML & LESS
  • LiveReload as you edit
  • Directory indexes
  • MIME Type file support

Supporting: MathJax, Chinese Characters, Table of Contents, Tables, Heading Anchors

Markserv directory index

:computer: Installation

# NPM
$ npm i -g markserv

Yarn

$ yarn global add markserv

:joystick: Usage

To start Markserv from the CLI

# Open closest README.md
$ readme

Open file

$ markserv README.md

Open a directory

$ markserv node_modules

Markserv CLI Splash

Start Markserv and open a file or directory.

# File
$ markserv ./path/to/file.md

Directory

$ markserv ./

Start Markserv and open the closest README.md file in the browser:

$ readme

:zap: Live Reload

To see real-time updates as you save your markdown files, you will need to install the LiveReload plugin for your browser:

With the Live Reload plugin installed and turned on, you should see the page reloading as you save your Markdown file.

Markserv Live Reload

:link: Markdown Links

You can link to an external Markdown file in the same way that you use GitHub Wiki links. You can use the example code here to see how external links work.

Example code:

[Skateboarding Dog!](tests/Linked-Markdown-Example.md)

Example link:

Skateboarding Dog!

:stopwatch: Just in Time Templating

Markserv allows you to include nested content. Templates are fetched and rendered when you request them in your browser. The

maxDepth
of includes is set to
10
.

If you would like to look at an example, you can look in the tests/templates directory of this repo.

To see the server output of this templating example:

$ git [email protected]/f1lt3r/markserv.git
$ cd markserv
$ markserv tests/templates/index.html

Include Markdown

Note: Any markdown files that you include will be transformed to HTML.

Where

foo/bar/baz/qux.md
equals:
## Qux

And Markserv renders the following content:

# Include Markdown
{markdown: foo/bar/baz/qux.md}

The server response will be:

Include Markdown

Foo Bar

Include HTML

Where

foo/bar/baz/qux.html
equals:

Qux

And Markserv renders the following content:

# Include Markdown
{html: foo/bar/baz/qux.html}

The server response will be:

Include Markdown

Qux

Include LESS

Note: Any LESS files that you include will be transformed to CSS.

Where

foo/bar/baz/qux.css
equals:
@link-color: green;
a {color: @link-color}

And Markserv renders the following content:


The server response will be:


:crossed_flags: Flags

To list the options/flags for the markserv CLI tool:

$ markserv --help

Changing the HTTP Port

You can change the HTTP Port like this:

markserv -p 80

Making Markserv available to external networks

In some cases

localhost
might be the address on which the server is listening, in which case it is hard to make the site available to external networks even with the right IP. Use the following as an example to make sure the server is accessible from external networks:
markserv -p 8642 -a 0.0.0.0

Above example runs the server on port

8642
and it can be accessed from external networks using public IP of the machine on which the server is running. If you want the server to keep running in a seperate thread even when you log out, use this:
nohup markserv -p 8642 -a 0.0.0.0 &

This will make the server instance persistent and will be available to access even when you log out or even when your ssh session closes (in case you are accessing a remote machine through ssh to set up

markserv
server)

:cupid: Credits

Thanks goes to these wonderful people (emoji key):


Alistair MacDonald

πŸ’»

ι™³η€›ζ΄²

πŸ’»

Kefei Lu

πŸ’»

Zhenfei You

πŸ’»

Andrew

πŸ’»

Daniel Perez

πŸ’»

Sushruth Shastry

πŸ’»

Patryk RzucidΕ‚o

πŸ’»

EstebanMarin

πŸ’»

Matthew Reishus

πŸ“–

Daniel Wennberg

πŸ’»

Pete Hodgson

πŸ’»

Deleted user

πŸ“–

Liam Dawson

πŸ’»

This project follows the all-contributors specification. Contributions of any kind welcome!

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.