node package manager

pagic

Pagic

Build Status npm package npm downloads Coveralls

The easiest way to generate static html page from markdown

Features

Getting started

Installation

npm install pagic -g

Markdown + Layout => HTML

Let's say we have a project like this:

docs/
├── public/
└── src/
    ├── _layout.js
    └── index.md

The _layout.js is a simple javascript module which contains a template string:

module.exports = function ({ title, content }) {
  return `
    <!doctype html>
    <html>
      <head>
        <title>${title}</title>
      </head>
      <body>
        ${content}
      </body>
    </html>
  `;
};

The index.md is a simple markdown file:

Pagic
 
The easiest way to generate static html page from markdown

Then run

pagic build

We'll get an index.html file in public directory:

docs/
├── public/
|   └── index.html
└── src/
    ├── _layout.js
    └── index.md

The content should be:

<!doctype html>
<html>
  <head>
    <title>Pagic</title>
  </head>
  <body>
    <h1 id="pagic">Pagic</h1>
    <p>The easiest way to generate static html page from markdown</p>
  </body>
</html>

Here we use markdown-it with plugins markdown-it-anchor and markdown-it-title to parse the markdown file.

Copy static files

If there are other static files which are not ended with .md or start with _, we will simply copy them:

docs/
├── public/
|   ├── css
|   |   └── site.css
|   └── index.html
└── src/
    ├── css
    |   └── site.css
    ├── _layout.js
    └── index.md

Sub page and sub layout

We can have sub directory which contains markdown files.

Sub directory can also have a _layout.js file.

For each markdown file, it will walk your file system looking for the nearest _layout.js as the template. It starts from the current directory of the markdown file and then moves to the parent directory until it finds the _layout.js

docs/
├── public/
|   ├── css
|   |   └── site.css
|   └── index.html
|   └── sub
|       └── index.html
└── src/
    ├── css
    |   └── site.css
    ├── _layout.js
    |── index.md
    └── sub
        ├── _layout.js
        └── index.md

Front matter

Front matter allows us add extra meta data to markdown:

---
author: xcatliu
published: 2017-03-02
---
 
Pagic
 
The easiest way to generate static html page from markdown

Then in _layout.js, we can get a frontMatter object which contains the meta data:

module.exports = function ({ title, content, frontMatter }) {
  return `
    <!doctype html>
    <html>
      <head>
        <title>${title}</title>
      </head>
      <body>
        ${content}
        <footer>
          Author: ${frontMatter.author},
          Published: ${frontMatter.published}
        </footer>
      </body>
    </html>
  `;
};

Yaml config file

We can set the configuration in _config.yml, the default is:

src_dir: src
public_dir: public

Injected variables

The variables which are injected to _layout.js:

Variable Interpretation
title The title of current page, usually is the first # Title in the markdown
content The content of current page
frontMatter The frontMatter object of current markdown
relativeToRoot The relative path from current markdown file to root directory
config The json format of _config.yml. You can add your custom data to it
filePath The current markdown file path

Use Pagic as cli

pagic build

We can use pagic build to build static page, there are some options while using build command:

pagic build [options]
 
# -w, --watch  watch src dir change
# -s, --serve  serve public dir
# -p, --port   override default port

pagic init

We can use pagic init to create a new Pagic folder:

pagic init <dir>

Use Pagic as a node module

It's also able to use it as a node module:

npm install pagic --save

Common usage

const Pagic = require('pagic');
 
const pagic = new Pagic();
pagic.build();

Watch file change

pagic.watch().build();
 
setTimeout(() => {
  pagic.unwatch();
}, 10000);

Development

npm install
npm start
npm test

LICENSE

MIT


Have fun with pagic!