Pagic

The easiest way to generate static html page from markdown

Features

Markdown + Layout => HTML: xxx.md + _layout.js => xxx.html
Copy Static Files: Copy other static files which are not ended with .md or start with _
Sub Page and Sub Layout: 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
Front Matter: Add extra meta data to markdown
relativeToRoot: inject the relativeToRoot variable to the _layout.js

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>
  `;
};

relativeToRoot

The last thing, we can get the relativeToRoot variable in the _layout.js, this helps us insert the relative resources:

module.exports = function ({ title, content, relativeToRoot }) {
  return `
    <!doctype html>
    <html>
      <head>
        <title>${title}</title>
        <link rel="stylesheet" href="${relativeToRoot}/css/site.css" />
      </head>
      <body>
        ${content}
      </body>
    </html>
  `;
};

_config.yml

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

src_dir: src
public_dir: public

Use Pagic as CLI

build

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

pagic build [options]

# -w, --watch  watch src dir change
# -s, --serve  serve public dir
# -p, --port   override default port

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

const Pagic = require('pagic');

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

Development

npm install
npm start
npm test

LICENSE

MIT

Have fun with pagic!