The easiest way to generate static html page from markdown, built with Deno π¦
Gagic is the second version of Pagic. Hard forked v0.9.1
Pagic supports up to Deno 1.3.3, so Gagic is developing Deno 1.4.0 and above for support.
# Install deno https://deno.land/#installation
curl -fsSL https://deno.land/x/install/install.sh | sh
# Install gagic
deno install --unstable --allow-read --allow-write --allow-net --name=gagic https://deno.land/x/gagic/mod.tsLet's say we have a project like this:
docs/
βββ public/
βββ src/
βββ _layout.tsx
βββ index.md
The src/_layout.tsx is a simple react component:
import { React, GagicLayout } from 'https://deno.land/x/gagic/mod.ts';
const Layout: GagicLayout = ({ 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:
# Gagic
The easiest way to generate static html page from markdown, built with Deno π¦Then run:
gagic buildWe'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>Gagic</title>
<meta charset="utf-8" />
</head>
<body>
<article>
<h1 id="gagic">Gagic</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:
import { React } from 'https://deno.land/x/gagic/mod.ts';
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 and yoshixmk
published: 2020-09-15
---
# Gagic
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:
import { React, GagicLayout } from 'https://deno.land/x/gagic/mod.ts';
const Layout: GagicLayout = ({ 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:
import { React } from 'https://deno.land/x/gagic/mod.ts';
const Hello = () => <h1>Hello world</h1>;
export default Hello;
export const frontMatter = {
title: 'Hello world',
author: 'xcatliu and yoshixmk',
published: '2020-05-20'
};It's able to configurate gagic by adding a gagic.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',
'gagic.config.ts',
'gagic.config.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 gagic.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 gagic.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 gagic build to build static pages, there are some options while using build command:
gagic build [options]
# --watch watch src dir change
# --serve serve public dir
# --port override default portHave fun with gagic!