Generate static html page from markdown, built with Deno

Gagic

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.

Live demo

Getting started

Installation

# 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

Markdown + Layout => HTML

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>

React component as a page

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>

Copy static files

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

Sub pages and layouts

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

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;

Front matter in react component

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'
};

Configuration

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.

Plugins and themes

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!

Use gagic as cli

`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

Download Details:

Author: yoshixmk

Source Code: https://github.com/yoshixmk/gagic

#deno #nodejs #node #javascript