The easiest way to generate static html page from markdown
- Markdown + Layout => HTML
- Copy static files
- Sub page and sub layout
- Front matter
- Yaml config file
- Injected variables
npm install pagic -gLet'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 markdownThen run
pagic buildWe'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.
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
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 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>
`;
};We can set the configuration in _config.yml, the default is:
src_dir: src
public_dir: publicThe 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 |
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 portWe can use pagic init to create a new Pagic folder:
pagic init <dir>It's also able to use it as a node module:
npm install pagic --saveconst Pagic = require('pagic');
const pagic = new Pagic();
pagic.build();pagic.watch().build();
setTimeout(() => {
pagic.unwatch();
}, 10000);npm install
npm start
npm testHave fun with pagic!
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent