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 { return ` <!doctype html> <html> <head> <title></title> </head> <body> </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:
Pagic Pagic The easiest way to generate static html page from markdown
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: xcatliupublished: 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 { return ` <!doctype html> <html> <head> <title></title> </head> <body> <footer> Author: , Published: </footer> </body> </html> `;};
Yaml config file
We can set the configuration in _config.yml
, the default is:
src_dir: srcpublic_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 = ; const pagic = ;pagic;
Watch file change
pagic; ;
Development
npm installnpm startnpm test
LICENSE
Have fun with pagic!