Maverick

English | 简体中文

Overview

Maverick is a static blog generator built with python. Like Hexo and Jekyll, it takes Markdown (.md) files as input, and output beautifully formated and well structured website pages (.html). It has a bunch of built-in useful features (feed, search, sitemap, etc.), with extended Markdown syntax and enhanced image processing pipeline.

If you are tired of intricate plugins and complicated configurations, just give Maverick a try. You can focus on writing, let Maverick take care of the rest.

Pull requests are surely welcome. If you have any questions or suggestions, please head to issue area and leave us a message. Before that, let's finish this document.

Usage

Maverick is built with modern Python, currently at least Python 3.5 is required, make sure you have it installed on your machine.

Install

Clone this repository:

git clone https://github.com/AlanDecode/Maverick.git ./Maverick && cd ./Maverick

Install dependencies:

pip install -r requirements.txt

If error occurs, please verify your Python and pip version. Then edit the default configuration file:

vi ./demo_src/config.py

For now let's use the default settings. Type this command in your terminal:

python3 mvrk.py --config ./demo_src/config.py --source_dir ./demo_src/ --build_dir ./dist/

...and a sample static site is generated in dist folder! You can then upload them to GitHub Pages or any other server.

Generate your own site

By default, Maverick searches all .md files recursively under demo_src folder, so put your Markdown files in it and run above command then everything you need will be in dist folder. Maverick uses so-called YAML frontmatter to get meta data of your articles, if you have tried Hexo or Jekyll, you should already be familiar with it; if you don't, let's look into it now.

File arrangement and frontmatter

In Maverick, arrangement of your source article files is not important, you can arrange them by category, date or anything you like, Maverick will try to find them automatically.

Instead, frontmatter of each Markdown file tells Maverick its slug, category, tags and publish date, etc. frontmatter is a short piece of text on top of each Markdown file, like this:

---
layout: post
title: A interesting story
slug: a-interesting-story
date: 2019-12-11 16:08
status: publish
author: AlanDecode
categories: 
  - Daily
tags: 
  - Travel
  - Family
---

<!-- Your content here -->

frontmatter starts and ends with ---, it stores information as key: value pair. All available options are listed bellow:

I suggest you keep a copy of sample articles come with Maverick as a reference to these options.

Configurations

Although Maverick is much simpler than many other generators, it does have a few configurations you need to take care of, which you can modify in config.py. All these options are listed bellow.

Options for Maverick

Options for Your Site

💡 Note: You can access other options by ${option_name}. For example ${site_prefix}logo.png will be parsed as /logo.png if you set site_prefix to /. When using this feature, watch out for infinite loops.

💡 Note: You can use ${static_prefix} instead of ${site_prefix} to reference static files, if you enabled jsDelivr as CDN service.

💡 Note: you can also use configuration file other than config.py, just specify it when build:

python ./build.py -c "./my_conf.py"
# or
python ./build.py --config "./my_conf.py"

Images and Static Assets

Maverick is a flexible generator, it does not require you to put your files in some fixed location, instead, by setting source_dir, it automatically detects all source files to build your site. But what about images and other static assets like fonts or others? Well, Maverick has its own rule to solve this problem.

Static Assets

If there is a folder named static under source_dir, Maverick will copy all contents in that folder to build_dir. For example, if a source_dir looks like this:

source_dir/
    - static/
        - favicon.ico
        - robots.txt
        - font/
    - ...

The result will be like this:

build_dir/
    - favicon.ico
    - robots.txt
    - fonts/

Simple, right?

Images

You can of course put all your images under static folder, however, Maverick is designed to handle images very smartly. In fact, you can put your images anywhere on your machine, or insert remote images by URL in your Markdown file, when generating your static site, Maverick will try to gather them all together, putting them into a unified position and taking care of the links in your article in the same time.

In this way, you can freely manage your images with any online services you like, or just save them locally on your machine and reference them by relative or absolute path in your article. Many Markdown editors (like the awesome [Typora]()) support inserting local images and can display them properly. This enables real-WYSIWYG (What You See Is What You Get). For example, if you have a folder structure like this:

source_dir/
    - assets/
        - pic.jpg
    - article.md

In article.md, you insert pic.jpg like bellow:

![](./assets/pic.jpg)

When parsing article.md, Maverick will try to find ./assets/pic.jpg on your machine, once been found, Maverick copies it to build_dir/archives/asstes/, and then change the link in article.md.

Here is one more reason why Maverick is designed this way. In many cases, for example, light-box and photo arrangements on web pages requires predefined image dimensions. Instead of fetching size information at front-end, parsing size information at building stage can dramatically improve the experience. Besides, this design can enable jsDelivr as CDN service for all your images.

It's special for remote images though. We can't easily get size information of them, so Maverick can try to download remote images to local disk and treat them as local images, this feature is disabled by default, you can turn it on by setting fetch_remote_imgs to True in configuration file. If you don't want to download full images to, just leave fetch_remote_imgs as False, Maverick will try to get the size of the image by downloading very small part of it (in most cases only 1~2 KB is needed).

All remote images and size information are cached locally, so Maverick won't download and parse them during every generation.

Markdown

Maverick uses mistune 0.8.4 as its back-bone Markdown parser, with some extending.

Math Equations

You can insert math equations with like this:

# inline math
$m\times n$

## block math
$$C_{m\times k}=A_{m\times n}\cdot B_{n\times k}$$

Code Highlighting

Just specify the language when inserting code block with markdown syntax, and it will automatically be highlighted:

​```cpp
int main(int argc , char** argv){
    std::cout << "Hello World!\n";
    return 0;
}
​```

Ruby

Type something like this:

I am {{Darth Vader:Your Father}}!

And it will be rendered as: I am Darth Vader (Your Father)!

Link Card

Type something like this:

[Name](link)+(image URL)

It will be rendered as a link card with a images and a title.

Inline Footnotes

Insert inline Footnotes like this:

Maverick is a staic blog generator[^Built with Python.].

DPlayer

Thanks to DPlayer, you can easily insert beautiful video player into your posts:

[dplayer]https://path/to/veideo.mp4[/dplayer]

You can add more options to it like this:

[dplayer data-theme="#b7daff"]https://path/to/video.mp4[/dplayer]

Checkout more options here.

Themes

Maverick has two built-in themes, Galileo and Kepler. You can easily switch between theme by setting template entry in config.py:

template = 'Galileo' # or 'Kepler'

For third-party themes, there are two ways to use them.

1. Put third-party theme under any local folder, and set template in config.py accordingly. For example, if you have such folder structure:

   /some/path/to/MyTheme/
   __init__.py

   Then you need to set template in config.py as:

   template = {
      "name": "MyTheme",
      "type": "local",
      "path": "/some/path/to/MyTheme/"
   }

2. Install theme from remote Git repository. If the theme is open sourced by Git, you can configure Maverick to use it directly. For example, you can also use Kepler theme like this:

   template = {
      "name": "Kepler",
      "type": "git",
      "url": "https://github.com/AlanDecode/Maverick-Theme-Kepler.git",
      "branch": "latest"
   }

   Please consult theme provider on install details.

Comments

Maverick has built-in Valine support, please refer to Valine Docs for more information. You need to fill valine entry in configuration file with at least these options:

valine = {
    "enable": True,
    "el": '#vcomments',
    "appId": "<your appId here>",
    "appKey": "<your appKey here>",
}

Development

Pull requests are surely welcome. See theme-Dev.md for documentation on developing a theme for Maverick.

Credits

Thank Typlog for their wonderful work on extended Markdown image syntax.

License

MIT © AlanDecode.