- 方便的图片管理
- 博客版本管理
- 在任何设备上写博客，包括浏览器
- 无需值守的自动化构建
- 免费、超快的全球 CDN
- 不需要在本地安装 NodeJS 这类运行环境（若要在本地写文章，需要安装 git）
为什么要使用 GitHub 写博客
./images/1.png 这样的链接）引用图片，自给自足，以最大程度保证持久性与可访问性。为什么要写一个生成器
hexo目录/source/_posts 这个路径下；而此时我使用 git 管理自己的博客源文件.## 通过网络链接引用
## 通过相对位置引用
## 通过绝对位置引用
现在，跟我一起动手实践吧
Blog-With-GitHub-Boilerplate 不变。为仓库开启 Pages 服务
https://<用户名>.github.io/Blog-With-GitHub-Boilerplate 这样的链接访问示例网站了。https://<用户名>.github.io/Blog-With-GitHub-Boilerplate/index.html 这个链接，对应的文件则是仓库根目录下的 index.html 文件，由于大家都用 index.html 这个文件名，因此也可以省略不写，其它链接同理。<用户名>.github.io。开启 Pages 服务后可以直接通过 http://<用户名>.github.io 访问。http://<用户名>.github.io/<仓库名> 访问。- master 分支（默认）
- master 分支中的 docs 文件夹
- gh-pages 分支
CNAME 文件或者在设置中绑定就行。此外，私有仓库也可以开启 Pages 服务，这十分适合用来发布博客，设想在 master 分支中存储源文件，是只自己可见的；将生成的网站发布到 gh-pages 分支，是公众可见的。这是兼具安全与便捷性的方案。为仓库添加一个 token
.github/workflows 文件夹下的 YML 配置文件启动 CI 流程。尝试修改一下网站设置
- 为你的网站起个名字，填写到
site_name这里 - 修改
author，email，description等选项为你的内容 - 其它选项也可以随意修改()
https://<用户名>.github.io/Blog-With-GitHub-Boilerplate 看是不是已经更新了。如果没有，请点击仓库标题下方的 Actions 按钮，在里面查看自动构建状态。尝试发布新的内容
我的第一篇文章.md，内容参考如下：---
layout: post
title: 我的第一篇文章
slug: my-first-awesome-post
date: 2019-12-17 20:34
status: publish
author: 熊猫小A
categories:
- 默认分类
tags:
- 博客
- Maverick
- GitHub
excerpt: Hello World!
---
这是我的第一篇文章。文章使用 GitHub 管理，并通过 GitHub Actions 自动构建与发布！
https://<用户名>.github.io/Blog-With-GitHub-Boilerplate，可见新文章已经发布了。与上一步同理，GitHub 检测到了新的更改，并启动了构建与部署的自动化流程。使用 jsDelivr 作为博客的 CDN 服务
jsDelivr is the only public CDN with a valid ICP license issued by the Chinese government, and hundreds of locations directly in Mainland China.
https://cdn.jsdelivr.net/gh/<用户名>/<仓库名>@<分支名>/<文件路径>
https://cdn.jsdelivr.net/gh/AlanDecode/site-Blog@gh-pages/favicon.ico
enable_jsdelivr 如下：enable_jsdelivr = {
"enabled": True,
"repo": "<你的用户名>/Blog-With-GitHub-Boilerplate@gh-pages"
}
这是我的第一篇文章。文章使用 GitHub 管理，并通过 GitHub Actions 自动构建与发布！
cdn.jsdelivr.net 开头。src/images 文件夹里，然后在文章中使用 Markdown 语法引用即可。进行更多的自定义与创作
src/static 文件夹中有一个 logo.png，这是示例 logo。你可以在这个文件夹中上传新的 logo 图片，最好是方形的图片，然后在 conf.py 中修改 site_logo 为 "${static_prefix}新的logo.png" 即可。site_prefix 设置为 "/<新的仓库名>/"。如果要把仓库名修改为 <用户名>.github.io 的形式，那么 site_prefix 设置为 "/" 即可。在本地进行创作
update_site.bat 、update_maverick.bat （Windows用），以及 update_site.sh、update_maverick.sh （Linux、macOS用）几个文件。update_site.xx 的作用是在本地修改了文章或者网站配置后，将修改推送到 GitHub；update_maverick.xx 则用于升级仓库中的 Maverick 版本。chmod +x ./update_site.sh
chmod +x ./update_maverick.sh
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"
git config --global credential.helper store
git clone <仓库链接>
# cd 到仓库文件夹后
git add .
git commit -m "添加修改"
git push
绑定自定义域名
<用户名>.github.io，然后回到仓库，在 src/static 文件夹中添加一个名叫 CNAME 的文件，内容填写你自己的域名。然后在 conf.py 中修改 site_prefix 为 "/"。稍等片刻，你的网站就能通过你的域名访问了。结语
from https://blog.imalan.cn/archives/blog-now-powered-by-maverick/
我曾几次把目光转向静态博客。诸如 Hexo、Jekyll 这类静态博客生成器让用户在本地编写 Markdown 文本，再由生成器完成从原始文件到博客网页的转换。某种程度上，这类程序让写作者从维护网站的繁琐中解脱出来，而专注创作本身。MWeb、Gridea 作为博客写作工具时也属于此类。
然而实践下来，仍然有两个问题没能得到解决：
- 博客源文件的管理问题。想要达到真正的内容与展示分离，就不应该限制源文件的存储方式。现在的生成器要么要求把内容存储到自己的库中，要么要求放在生成器目录下的特定位置，某些甚至对目录结构都有要求。这并不是我想要的；
- 图片等静态资源的处理问题。Markdown 对图片的处理一直都是痛点。我不希望把图片放在任何第三方图床，且不提上传图片-获得外链-插入外链这个过程多么不便，远程图床还有随时跑路的风险；而现在的生成器又不能很好地处理本地图片，至少处理起来并不优雅。
Alan Key 的一句名言，被 Steve Jobs 引用后众人皆知：
People who are really serious about software should make their own hardware.
拿来活用，则「任何认真对待博客的人都应该自己写博客系统」。这话说起来固然偏执，但确实为吹毛求疵的人指了一条明路。既然现在的轮子都不满意，那就应该造自己的轮子。本着学习与探索的目的，我使用 Python 自己写了一个静态博客生成器，取名 Maverick，开源于 GitHub。它现在正驱动着我的个人 Wiki。
项目主页 | 个人博客 | 演示站点 | 欢迎反馈与Star
现在可以说说 Maverick 本身。大致上，它与 Hexo 等相似，都是通过解析 Markdown 文件生成网页。不过我在设计它时考虑到了上文所述的系列问题，并做了针对性的改进。
首先是 Maverick 对源文件的处理。Maverick 不限制源文件的存储位置，你可以把文章目录放在电脑上的任何路径下，例如 Dropbox、iCloud Drive，以便备份、同步、版本管理，以及在任何设备上用任何编辑器写作。Maverick 也不限制源文件的组织结构，你可以按照你喜欢的方式组织它们，按时间、按类别都可以。
为了达到这一点，Maverick 通过叫做 source_dir 的选项在指定路径下搜索所有 Markdown 文件，并根据里面提供的信息将它们分门别类，生成日期标签等等。这些内容被称作 frontmatter，也就是使用 Hexo 等写文章时顶部的使用 --- 包裹起来的那部分东西。这样的设计让以前的内容可以被复用，也便于以后的迁移。
此外是对图片的处理。Maverick 允许在 Markdown 文件中引用任何位置的图片，并且都能在生成网站时合适地处理它们。若你在原始文本中通过绝对路径或者相对路径引用本地图片，Maverick 会在生成网站时自动寻找它们，并把它们复制到统一的位置，同时修改文章里的引用链接；若通过 URL 引用了远程图片，则（可选地）将它们下载到本地缓存，按本地图片对待。这样处理的好处很多。
- Typora、VS Code 等软件都支持插入与预览本地图片。尤其是 Typora，本身还提供了插入图片时自动将图片复制到相对文章的某个目录的功能，这与 Maverick 的处理方式十分契合；
- 通过本地缓存，减小了图片丢失的风险。若图床跑路，你还可以在本地找到一份备份，不会影响你发布的内容；
- 虽然目前还没有实现这个功能，但通过本地化以及统一的发布流程，可以实现自动图片处理（例如压缩）；
- 可以提前获知图片的大小尺寸等信息，并在网页展示时提供优化的体验（比如图片排版与点击放大）。
而这一切都发生在生成站点时，不会对原本的文章有任何影响，不需要在文章里多加什么标注或者声明。只需要用标准的 Markdown 语法引入图片就好。此外，不论是缓存还是尺寸信息，Maverick 都会在生成时缓存下来，不会反反复复地请求与解析。
除了以上两点改进，Maverick 还自带了一些博客的常用功能，例如 RSS 源生成、实时搜索、Sitemap 等。这一切你都可以在示例站点上体验到。目前，Maverick 没有插件机制，但以我自己的体验而言，应该具备了个人博客应有的功能。
我在 Lepture 开发的 Markdown 解析器 mistune 基础上进行扩展，添加了一些 Markdown 语法，使之能够良好地支持代码高亮、行内脚注、数学公式、图片排版等。
网页端的展示方面，Maverick 使用自带的主题 Galileo。这是一个比较简洁的主题，以文字阅读体验为重心开发，样式上借鉴了安妮薇日报与 hexo-theme-cactus 的设计。文字排版效果请参见 Typography - Maverick。
总之，我从自己的观察与需求出发，自己写了一款静态博客生成器。本文只覆盖了关于 Maverick 的很小的一部分，欢迎各位移步 项目主页 阅读完整的说明。
这是我用 Python 写的第一个像点样的东西，因此不免有些遗漏与错误，任何建议与反馈都十分欢迎。当然 Star 则是特别欢迎😜。
那么，就这样，感谢各位阅读。周末愉快~
from https://blog.imalan.cn/archives/blog-now-powered-by-maverick/
A static blog generator built with Python.
https://alandecode.github.io/Maverick/
English | 简体中文
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.
Maverick is built with modern Python, currently at least Python 3.5 is required, make sure you have it installed on your machine.
Clone this repository:
git clone https://github.com/AlanDecode/Maverick ./Maverick && cd ./MaverickInstall dependencies:
pip3 install -r requirements.txt --userIf error occurs, please verify your Python and pip version. Then edit the default configuration file:
vi ./demo_src/config.pyFor 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.
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.
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.
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.
| 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 | { "enabled": False, "repo": "" } | 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. |
| 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 | - | Maverick now supports Valine as its comment system. Please refer to Comments for more information. |
head_addon | - | Content here will be added to <head> tag of generated HTMLs, you can put some meta tag here, or use <link> and <script> to import custom CSS and JavaScript files. |
footer_addon | - | Content here will be added to <footer> tag. You can add some additional info here. |
body_addon | - | Content here will be added to <body> tag, external JavaScripts and can be put here. |
language | "english" | Site language. |
background_img | - | Background image for your site. Better be light-colored. |
💡 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"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.
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?
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:
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.
Maverick uses mistune 0.8.4 as its back-bone Markdown parser, with some extending.
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}$$
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;
}
```
Type something like this:
I am {{Darth Vader:Your Father}}!
And it will be rendered as: I am Darth Vader!
Type something like this:
[Name](link)+(image URL)
It will be rendered as a link card with a images and a title.
Insert inline Footnotes like this:
Maverick is a staic blog generator[^Built with Python.].
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.
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.
Put third-party theme under any local folder, and set
templatein config.py accordingly. For example, if you have such folder structure:/some/path/to/MyTheme/ __init__.pyThen you need to set
templatein config.py as:template = { "name": "MyTheme", "type": "local", "path": "/some/path/to/MyTheme/" }
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
Keplertheme 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.
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>",
}Pull requests are surely welcome. See theme-Dev.md for documentation on developing a theme for Maverick.
from https://github.com/AlanDecode/Maverick
-----
在windows上的cmd.exe或git bash里运行：
python3 mvrk.py --config ./demo_src/config.py --source_dir ./demo_src/ --build_dir ./dist/
如果遇到出错提示：ModuleNotFoundError: No module named 'chardet'
则运行pip3 install chardet 。
之后运行上面的命令，如果还是遇到同样的出错提示，则运行：
python mvrk.py --config ./demo_src/config.py --source_dir ./demo_src/ --build_dir ./dist/
（把python3改为python)
参见：https://github.com/AlanDecode/Maverick/issues/37 
