The easiest way to generate static html page from markdown, built with Deno! π¦
- Markdown + Layout => HTML
- React component as a page
- Copy static files
- Sub pages and layouts
- Front matter
- Configuration
- Plugins and themes
WARNING: This project is under development so api would changes without announce. The stable version will some soon when v1.0.0 finished.
- Deno X ranking (GitHub)
- TypeScript ε ₯ι¨ζη¨ (GitHub)
- Deno ι»η δΉζ― (GitHub)
- Deno δΈζζε (GitHub)
- Add my site as a demo π
# Install deno https://deno.land/#installation
curl -fsSL https://deno.land/x/install/install.sh | sh
# Install pagic
deno install --unstable --allow-read --allow-write --allow-net https://deno.land/x/pagic/mod.ts
Let's say we have a project like this:
docs/
βββ public/
βββ src/
βββ _layout.tsx
βββ index.md
The src/_layout.tsx
is a simple react component:
// @deno-types="https://deno.land/x/types/react/v16.13.1/react.d.ts"
import React from 'https://dev.jspm.io/react@16.13.1';
import { PagicLayout } from 'https://deno.land/x/pagic/mod.ts';
const Layout: PagicLayout = ({ title, content }) => (
<html>
<head>
<title>{title}</title>
<meta charSet="utf-8" />
</head>
<body>{content}</body>
</html>
);
export default Layout;
The src/index.md
is a simple markdown file:
# Pagic
The easiest way to generate static html page from markdown, built with Deno! π¦
Then run:
pagic build
We'll get an index.html
file in public
directory:
docs/
βββ public/
| βββ index.html
βββ src/
βββ _layout.tsx
βββ index.md
The content should be:
<html>
<head>
<title>Pagic</title>
<meta charset="utf-8" />
</head>
<body>
<article>
<h1 id="pagic">Pagic</h1>
<p>The easiest way to generate static html page from markdown, built with Deno! π¦</p>
</article>
</body>
</html>
A react component can also be built to html:
docs/
βββ public/
| βββ index.html
| βββ hello.html
βββ src/
βββ _layout.tsx
βββ index.md
βββ hello.tsx
Here we build src/hello.tsx
to public/hello.html
, using src/_layout.tsx
as the layout.
src/hello.tsx
is a simple react component:
// @deno-types="https://deno.land/x/types/react/v16.13.1/react.d.ts"
import React from 'https://dev.jspm.io/react@16.13.1';
const Hello = () => <h1>Hello World</h1>;
export default Hello;
And public/hello.html
would be:
<html>
<head>
<title></title>
<meta charset="utf-8" />
</head>
<body>
<h1>Hello World</h1>
</body>
</html>
If there are other static files which are not end with .{md,tsx}
or (start with _
and end with .tsx
), we will simply copy them:
docs/
βββ public/
| βββ assets
| | βββ index.css
| βββ index.html
| βββ hello.html
βββ src/
βββ assets
| βββ index.css
βββ _layout.tsx
βββ _sidebar.tsx
βββ index.md
βββ hello.tsx
We can have sub directory which contains markdown or component.
Sub directory can also have a _layout.tsx
file.
For each markdown or react component, it will walk your file system looking for the nearest _layout.tsx
. It starts from the current directory and then moves to the parent directory until it finds the _layout.tsx
.
docs/
βββ public/
| βββ assets
| | βββ index.css
| βββ index.html
| βββ hello.html
| βββ sub
| βββ index.html
βββ src/
βββ assets
| βββ index.css
βββ _layout.tsx
βββ _sidebar.tsx
|ββ index.md
βββ sub
βββ _layout.tsx
βββ index.md
Front matter allows us add extra meta data to markdown:
---
author: xcatliu
published: 2020-05-20
---
# Pagic
The easiest way to generate static html page from markdown, built with Deno! π¦
Every item in the front matter will pass to the _layout.tsx
as the props:
// @deno-types="https://deno.land/x/types/react/v16.13.1/react.d.ts"
import React from 'https://dev.jspm.io/react@16.13.1';
import { PagicLayout } from 'https://deno.land/x/pagic/mod.ts';
const Layout: PagicLayout = ({ title, content, author, published }) => (
<html>
<head>
<title>{title}</title>
<meta charSet="utf-8" />
</head>
<body>
{content}
<footer>
Author: ${author}, Published: ${published}
</footer>
</body>
</html>
);
export default Layout;
In react component we can export a frontMatter
variable:
// @deno-types="https://deno.land/x/types/react/v16.13.1/react.d.ts"
import React from 'https://dev.jspm.io/react@16.13.1';
const Hello = () => <h1>Hello World</h1>;
export default Hello;
export const frontMatter = {
title: 'Hello World',
author: 'xcatliu',
published: '2020-05-20'
};
It's able to configurate pagic by adding a pagic.config.ts
file. The default configuration is:
export default {
srcDir: '.',
outDir: 'dist',
include: undefined,
exclude: [
// Dot files
'{,**/}.*',
// Node common files
'{,**/}package.json',
'{,**/}package-lock.json',
'{,**/}node_modules',
// pagic.config.ts and pagic.config.tsx
'pagic.config.{ts,tsx}',
// https://docs.npmjs.com/using-npm/developers.html#keeping-files-out-of-your-package
'{,**/}config.gypi',
'{,**/}CVS',
'{,**/}npm-debug.log'
// ${config.outDir} will be added later
],
root: '/',
theme: 'default',
plugins: ['clean', 'init', 'md', 'tsx', 'script', 'layout', 'out'],
watch: false,
serve: false,
port: 8000
};
Your pagic.config.ts
will be deep-merge to the default config, that is, your exclude
and plugins
will be appended to default, not replace it.
As you see default plugins are set to ['init', 'md', 'tsx', 'script', 'layout', 'write']
.
We can add the optional plugins by setting the plugins
in the pagic.config.ts
file:
export default {
srcDir: 'site',
plugins: ['sidebar']
};
sidebar
plugin will add a sidebar
properity to the props.
We can also add our own plugin like this:
import myPlugin from './myPlugin.tsx';
export default {
srcDir: 'site',
plugins: [myPlugin]
};
To develop a myPlugin
please checkout the built-in plugins.
Themes is under development, please come back later!
We can use pagic build
to build static pages, there are some options while using build
command:
pagic build [options]
# --watch watch src dir change
# --serve serve public dir
# --port override default port
Have fun with pagic!