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.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:
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 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>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!
gagic build
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 port
Author: yoshixmk
Source Code: https://github.com/yoshixmk/gagic
#deno #nodejs #node #javascript