# Mdblog
[![crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
![MIT/Apache2 licensed][license-image]
[![dependency status][deps-image]][deps-link]
[![Build Status][travis-image]][travis-link]
[crate-image]: https://img.shields.io/crates/v/mdblog.svg
[crate-link]: https://crates.io/crates/mdblog
[docs-image]: https://docs.rs/mdblog/badge.svg
[docs-link]: https://docs.rs/mdblog
[license-image]: https://img.shields.io/crates/l/mdblog.svg
[deps-image]: https://deps.rs/repo/github/fugangqiang/mdblog.rs/status.svg
[deps-link]: https://deps.rs/repo/github/fugangqiang/mdblog.rs
[travis-image]: https://travis-ci.org/FuGangqiang/mdblog.rs.svg?branch=master
[travis-link]: https://travis-ci.org/FuGangqiang/mdblog.rs
静态博客构建器，特性有：
* 支持 TeX 数学公式
* 使用文件路径生成博客文章 url
* 使用文件名作为博客文章标题
* 可以隐藏博客文章（首页文章列表不显示）
可以通过[示例博客网址](https://fugangqiang.github.io/mdblog.rs/)来进一步了解 `mdblog`。
# 安装
`mdblog` 由 rust 语言（2018 版）实现, 需要使用 `cargo` 命令安装:
```
cargo +nightly install mdblog
```
上面命令会将 `mdblog` 安装在 cargo 的二进制安装文件夹中，linux 操作系统下通常是 `~/.cargo/bin/`。
# 命令使用
`mdblog` 命令使用说明如下：
```
$ mdblog -h
static site generator from markdown files
USAGE:
mdblog <SUBCOMMAND>
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
SUBCOMMANDS:
build Build the blog static files
help Prints this message or the help of the given subcommand(s)
init Initialize the blog directory layout
new Create a blog post
serve Serve the blog, rebuild on change
theme Blog theme operations
```
通过下面方法检查子命令使用方法：
```
$ mdblog serve -h
Serve the blog, rebuild on change
USAGE:
mdblog serve [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-p, --port <port> Serve the blog at http://127.0.0.1:<port> [default: 5000]
```
### 初始化博客
```
$ mdblog init myblog
```
上面命令初始化博客文件夹(`myblog`)，目录结构如下：
```
myblog
├── config.toml
├── media
├── posts
│ ├── hello.md
│ └── math.md
└── _themes
```
* `config.toml`: 博客配置文件
* `media`: 博客媒体文件夹，可以在里面放一些图片、视频文件
* `posts`: 博客文章文件夹
* `posts/hello.md`: 博客文章的一个 `markdown` 示例
* `_themes`: 博客样式文件夹
### 构建博客
```
$ cd myblog
$ mdblog build
```
上面命令会构建博客网站静态文件，存放到 `_build` 目录中，此时博客目录结构如下：
```
myblog
├── config.toml
├── media
├── posts
│ ├── hello.md
│ └── math.md
├── _themes
└── _builds
```
* `_builds`: 博客网站静态文件顶层目录
### 本地预览博客
```
$ mdblog serve
```
上面命令会自动在浏览器打开博客首页，此后当修改博客时，会自动重构博客静态文件。
### 创建博客文章
```
$ mdblog new another
```
上面命令生成一篇新的博客文章，
标题为 `another`，
文章文件路径为 `posts/another.md`，
直接编辑这个文件，
当 `serve` 命令运行时，会自动更新博客文章内容，
然后刷新一下浏览器相关页面，
预览新的博客内容。
# 博客配置文件：config.toml
```toml
site_url = ""
site_name = "Mdblog"
site_motto = "Simple is Beautiful!"
footer_note = "Keep It Simple, Stupid!"
media_dir = "media"
build_dir = "_build"
theme = "simple"
theme_root_dir = "_themes"
rebuild_interval = 2
posts_per_page = 20
```
上面是博客配置的选项及其默认值，说明如下：
- site_url: 博客首页 url，如果想要博客作为现有一个网站的子内容，挂载到某个 url 路径下，可以配置这个选项
- site_name: 博客名称，博客顶栏显示
- site_motto: 博客格言
- footer_note: 博客底栏备注
- media_dir: 媒体文件夹路径
- build_dir: 博客最终构建的静态文件存放路径
- theme: 博客样式名
- theme_root_dir: 博客样式配置文件路径
- rebuild_interval: `serve` 命令时，修改博客出发重新构建时间间隔，单位为秒
- posts_per_page: 首页文章目录页面每页文章链接数量
博客配置文件的使用示例可以参考 `docs` 目录的相关配置。