Pagic

The easiest way to generate static html page from markdown

Features

Markdown + Layout => HTML
Copy static files
Sub page and sub layout
Front matter
Yaml config file
Injected variables

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!