pagic v0.6.0
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 -gMarkdown + Layout => HTML
Let's say we have a project like this:
docs/
├── public/
└── src/
├── _layout.js
└── index.mdThe _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 markdownThen run
pagic buildWe'll get an index.html file in public directory:
docs/
├── public/
| └── index.html
└── src/
├── _layout.js
└── index.mdThe 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.mdSub 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.mdFront 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 markdownThen 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: publicInjected variables
The variables which are injected to _layout.js:
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 portpagic 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 --saveCommon 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 testLICENSE
Have fun with pagic!