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:

| Key | Required | Default Value | Possible Value | Explanation | | :----------: | -------- | ------------- | ---------------------- | ------------------------------------------------------------ | | layout | false | post | post, page | Type of this article. | | title | true | - | - | The of this article | | slug | true | title | - | Maverick uses this value to generate URL of this article. For example: https://me.com/archives/a-interesting-story. | | date | true | - | - | Publish date of this article in yyyy-mm-dd hh:ss format. | | status | false | publish | publish, hidden, draft | Status of this article. | | author | false | - | - | Author of this article. | | excerpt | false | - | - | Will be used as excerpt of this article in home page and HTML head tag. If not set, Maverick will try to find <!--more--> and use content before as excerpt. If still not found, the first paragraph will be used. | | showfull | false | false | true, false | If set to true, full content will show in home page. | | comment | false | false | true, false | Turn on comment for this article. See how to enable comment in Comment section. | | tags | false | - | - | Tags of this article. If there are multiple tags, write them as above. Don't forget spaces before and after -. | | categories | false | - | - | Categories of this article. If there are multiple categories, write them as above. Don't forget spaces before and after - |

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

| Option | Default Value | Explanation | | ------------------------- | ----------------------------------------------- | ------------------------------------------------------------ | | site_prefix | "/" | This value will be used to generate permalinks of your posts. Possible values are like https://myblog.com/ or https://me.com/blog/ or just /blog/. If you want to put your site under sub directory, this option can be useful. Don't forget / at the end. | | source_dir | "./test_src/" | A directory in which Maverick will try to find your articles. This can be any location on your machine, so feel free to store your articles in Dropbox, iCloud Drive or anywhere else to get them synced across multiple devices. | | build_dir | "./test_dist/" | Where Maverick should place all generated HTML files. This can be any location on your machine, just make sure you have write permission on it. | | template | "Galileo" | Specify the template to render your site. Please refer to Themes for more details. | | index_page_size | 10 | The number of posts to show per page, change it to any number you like. | | archives_page_size | 30 | The number of posts to show per page in archive list, category list and tag list. | | fetch_remote_imgs | False | Specify how Maverick will take care of your images. Please refer to Images and Static Assets for more details. | | locale | Asia/Shanghai | Specify where you are. Valid options are listed here. | | enable_jsdelivr | {<br />"enabled": False,<br />"repo": ""<br />} | If you host your site on GitHub Pages, this option can enable jsDelivr as CDN service for all your static files, including JS files, CSS files and images. See config.py and preview site for an example. Basically, set "enabled" to True and set "repo" to <user>/<repo>@<branch>. | | category_by_folder | False | Category contents by folder structure rather than front-matter. |

Options for Your Site

| Option | Default Value | Explanation | | ----------------- | ----------------------------------------- | ------------------------------------------------------------ | | site_name | "Hellow Maverick!" | Website name. Change it to something really cool! | | site_logo | - | Website logo. Better be a square image. | | site_build_date | "2019-12-06T12:00+08:00" | When you build this site. | | author | - | Author's name. | | email | - | Author's email. | | author_homepage | "/" | Author's homepage. | | description | "A marvelous site powered by Maverick!" | Description of your site. | | keywords | - | Four or five keywords about your site. | | external_links | - | Will be used in Links section on home page. | | nav | - | Will be used to generate navigations behind site title. | | social_links | - | Will be used to generate social links behind site title. | | valine | -