Skip to content
This repository has been archived by the owner on Dec 27, 2020. It is now read-only.
/ gagic Public archive

The easiest way to generate static html page from markdown, built with Deno πŸ¦• Hard forked by Pagic.

License

Notifications You must be signed in to change notification settings

yoshixmk/gagic

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

27 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Gagic

(Deno) Test Lint nest badge

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.

Features

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

LICENSE

MIT


Have fun with gagic!

About

The easiest way to generate static html page from markdown, built with Deno πŸ¦• Hard forked by Pagic.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published