# pagic

> The easiest way to generate static html page from markdown

Latest version **0.6.0** (published 2017-04-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install pagic
pnpm add pagic
yarn add pagic
bun add pagic
```

Provides the command `pagic`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.0 |
| Published | 2017-04-03 |
| First published | 2017-03-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 12 |
| Known vulnerabilities | 0 (+6 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1653 |
| Author | xcatliu |
| Maintainers | xcatliu |
| Keywords | pagic, static, page, generator, markdown |

## Links

- npm: https://www.npmjs.com/package/pagic
- Repository: https://github.com/xcatliu/pagic
- Homepage: https://github.com/xcatliu/pagic#readme
- Issues: https://github.com/xcatliu/pagic/issues
- npm.io page: https://npm.io/package/pagic

## Dependencies (12)

- [glob](https://npm.io/package/glob.md) ^7.1.1
- [js-yaml](https://npm.io/package/js-yaml.md) ^3.8.2
- [chokidar](https://npm.io/package/chokidar.md) ^1.6.1
- [ecstatic](https://npm.io/package/ecstatic.md) ^2.1.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^2.0.0
- [commander](https://npm.io/package/commander.md) ^2.9.0
- [markdown-it](https://npm.io/package/markdown-it.md) ^8.3.0
- [front-matter](https://npm.io/package/front-matter.md) ^2.1.2
- [node-prismjs](https://npm.io/package/node-prismjs.md) ^0.1.0
- [find-parent-dir](https://npm.io/package/find-parent-dir.md) ^0.3.0
- [markdown-it-title](https://npm.io/package/markdown-it-title.md) ^1.0.4
- [markdown-it-anchor](https://npm.io/package/markdown-it-anchor.md) ^4.0.0

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 0.6.0 (latest) — 2017-04-03
- 0.5.0 — 2017-03-14
- 0.4.1 — 2017-03-11
- 0.4.0 — 2017-03-10
- 0.3.0 — 2017-03-03
- 0.2.0 — 2017-03-02
- 0.1.1 — 2017-03-01
- 0.1.0 — 2017-03-01

## README

# Pagic

[![Build Status](https://img.shields.io/travis/xcatliu/pagic.svg)](https://travis-ci.org/xcatliu/pagic) [![npm package](https://img.shields.io/npm/v/pagic.svg)](https://www.npmjs.org/package/pagic) [![npm downloads](http://img.shields.io/npm/dm/pagic.svg)](https://www.npmjs.org/package/pagic) [![Coveralls](https://img.shields.io/coveralls/xcatliu/pagic.svg)](https://coveralls.io/github/xcatliu/pagic)

The easiest way to generate static html page from markdown

## Features

- [Markdown + Layout => HTML](#markdown--layout--html)
- [Copy static files](#copy-static-files)
- [Sub page and sub layout](#sub-page-and-sub-layout)
- [Front matter](#front-matter)
- [Yaml config file](#yaml-config-file)
- [Injected variables](#injected-variables)

## Getting started

### Installation

```bash
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:

```js
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:

```markdown
# Pagic

The easiest way to generate static html page from markdown
```

Then run

```bash
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:

```html
<!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](https://github.com/markdown-it/markdown-it) with plugins [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) and [markdown-it-title](https://github.com/valeriangalliat/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:

```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:

```js
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:

```yaml
src_dir: src
public_dir: public
```

### Injected variables

The variables which are injected to `_layout.js`:

<div class="scroll-view">
  <table class="table">
    <thead>
      <tr>
        <th>Variable</th>
        <th>Interpretation</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code>title</code></td>
        <td>The title of current page, usually is the first <code># Title</code> in the markdown</td>
      </tr>
      <tr>
        <td><code>content</code></td>
        <td>The content of current page</td>
      </tr>
      <tr>
        <td><code>frontMatter</code></td>
        <td>The frontMatter object of current markdown</td>
      </tr>
      <tr>
        <td><code>relativeToRoot</code></td>
        <td>The relative path from current markdown file to root directory</td>
      </tr>
      <tr>
        <td><code>config</code></td>
        <td>The json format of <code>_config.yml</code>. You can add your custom data to it</td>
      </tr>
      <tr>
        <td><code>filePath</code></td>
        <td>The current markdown file path</td>
      </tr>
    </tbody>
  </table>
</div>

## Use Pagic as cli

### `pagic build`

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

```bash
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:

```bash
pagic init <dir>
```

## Use Pagic as a node module

It's also able to use it as a node module:

```bash
npm install pagic --save
```

### Common usage

```js
const Pagic = require('pagic');

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

### Watch file change

```js
pagic.watch().build();

setTimeout(() => {
  pagic.unwatch();
}, 10000);
```

## Development

```bash
npm install
npm start
npm test
```

## LICENSE

[MIT](./LICENSE)

---

Have fun with pagic!

---
_Source: https://npm.io/package/pagic · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
