/markdown-blog

🍭 Markdown-Blog 是一款小而美的Markdown静态博客程序 | Markdown-Blog is incredibly fast, easy to use, and converts Markdown formatted text files into beautifully rendered HTML pages.

Primary LanguageGoMIT LicenseMIT

GitHub Checks State GitHub Issues StyleCI GitHub Latest Release GitHub Last Commit Go Report Docker Image Size

中文 | English

Markdown-Blog 是一款小而美的Markdown静态博客程序

如果你和我一样,平时喜欢使用markdown文件来记录自己的工作与生活中的点滴,又希望把这些记录生成个人博客,那Markdown-Blog再适合不过了。它简洁、轻快,部署简单,可以把markdown文件快速变为个人博客,它不需要管理后台,无需进行文章的二次发布。

案例

TechMan'Blog

Web端

Style Preveiw
Dark pc dark
Light pc white

移动端

Dark Light
mobile dark mobile white

支持平台

Windows、Linux、Mac OS

更新

  • [v1.1.1] 2023-05-20

    • 支持设置备案号
    • 修复缓存参数失效
    • 支持读取本地文件,包括但不限于图片
    • windows环境解析问题
    • MD文件夹,仅读取markdonw文件
    • 其他已知问题修复
  • [v1.1.0] 2022-11-26

    • 支持评论
    • 参数设置,支持从本地文件读取(config.yml)
    • 支持加载 favicon.ico
    • 其他已知问题修复
  • [v1.0.0] 2022-11-20

    • 支持 Docker 部署
    • 打包静态文件,优化为单一程序,不再外挂 web 目录
    • 其他已知问题修复
  • [v0.1.1] 2022-11-12

    • 新增第三方分析统计配置,包括:百度、谷歌
    • 支持配置页面缓存时间
    • 移动端样式优化
    • 其他已知问题修复
  • [v0.0.5] 2022-11-06

    • 支持 TOC 语法,当文件内容首行使用 [toc] 会自动解析
    • 新增明亮🔆主题,支持明暗切换
    • 其他已知问题修复

安装

二进制

  1. 下载 release

  2. 解压

tar zxf markdown-blog-v0.0.5-linux-amd64.tar.gz
  1. 创建 markdown 文件目录
cd markdown-blog-linux-amd64
mkdir md
echo "### Hello World" > ./md/主页.md
  1. 运行
./markdown-blog web
  1. 访问 http://127.0.0.1:5006,查看效果

Docker

  1. 下载
docker pull willgao/markdown-blog:latest
  1. 启动

    • 线上环境
    docker run -dit --rm --name=markdown-blog \
    -p 5006:5006 \
    -v $(pwd)/md:/md -v $(pwd)/cache:/cache \
    willgao/markdown-blog:latest
    
    • 开发环境
    docker run -dit --rm --name=markdown-blog \
    -p 5006:5006 \
    -v $(pwd)/md:/md -v $(pwd)/cache:/cache \
    willgao/markdown-blog:latest \
    -e dev
    
  2. 访问 http://127.0.0.1:5006,查看效果

  3. 其他用法

# 查看帮助
docker run -dit --rm --name=markdown-blog \
    -p 5006:5006 \
    -v $(pwd)/md:/md -v $(pwd)/cache:/cache \
    willgao/markdown-blog:latest -h


# 设置 title
docker run -dit --rm --name=markdown-blog \
    -p 5006:5006 \
    -v $(pwd)/md:/md -v $(pwd)/cache:/cache \
    willgao/markdown-blog:latest \
    -t "TechMan'Blog"


# 设置 谷歌统计
docker run -dit --rm --name=markdown-blog \
    -p 5006:5006 \
    -v $(pwd)/md:/md -v $(pwd)/cache:/cache \
    willgao/markdown-blog:latest \
    -t "TechMan'Blog" \
    --analyzer-google "De44AJSLDdda"

使用

命令

  • markdown-blog
    • -h 查看版本
    • web 运行博客服务
  • markdown-blog web
    • --config FILE 加载配置文件, 默认为空
    • --dir value, -d value 指定markdown文件夹,默认:./md/
    • --title value, -t value web服务标题,默认:"Blog"
    • --port value, -p value web服务端口,默认:5006
    • --env value, -e value 运行环境, 可选:dev,test,prod,默认:"prod"
    • --index value, -i value 设置默认首页的文件名称, 默认为空
    • --cache value, -c value 设置页面缓存时间,单位分钟,默认3分钟
    • --icp value ICP备案号, 默认为空
    • --copyright value 版权年份,默认当前年份,如:2023,在配置了ICP后才有效
    • --fdir value markdown目录下的静态资源目录名称,比如图片等,默认"public"
    • --analyzer-baidu value 设置百度分析统计器
    • --analyzer-google value 设置谷歌分析统计器
    • --gitalk.client-id value 设置 Gitalk ClientId, 默认为空
    • --gitalk.client-secret value 设置 Gitalk ClientSecret, 默认为空
    • --gitalk.repo value 设置 Gitalk Repo, 默认为空
    • --gitalk.owner value 设置 Gitalk Owner, 默认为空
    • --gitalk.admin 设置 Gitalk Admin, 默认为数组 [gitalk.owner]
    • --gitalk.labels 设置 Gitalk Admin, 默认为数组 ["gitalk"]
    • --ignore-file value 设置忽略文件, eg: demo.md
    • --ignore-path value 设置忽略文件夹, eg: demo
    • -h 查看版本

运行参数

支持从配置文件读取配置项,不过运行时指定参数优先于配置文件,配置内容参考 config/config.yml.tmp

配置文件

  1. 新建配置文件 config/config.yml

  2. 启动时加载配置文件

  • 二进制文件
./markdown-blog web --config ./config/config.yml
  • Docker
docker run -dit --rm --name=markdown-blog \
-p 5006:5006 \
-v $(pwd)/md:/md -v $(pwd)/cache:/cache -v $(pwd)/config:/config \
willgao/markdown-blog:latest --config ./config/config.yml

默认首页

如果启动时未指定 index,程序默认以导航中的第一个文件作为首页

评论插件

评论插件使用的是 Gitalk,在使用前请阅读插件使用说明 English | 中文

新增 gitalk 配置项,启动时加载配置文件即可

gitalk:
    client-id: "你的 github oauth app client-id,必填。 如: ad549a9d085d7f5736d3"
    client-secret: "你的 github oauth app client-secret,必填。 如: 510d1a6bb875fd5031f0d613cd606b1d"
    repo: "你准备用于评论的项目名称,必填。 如: blog-issue"
    owner: "你的Github账号,必填。"
    admin:
        - "你的Github账号"
    labels:
        - "自定义issue标签,如: gitalk"

分析统计器

百度

1. 访问 https://tongji.baidu.com 创建站点,获取官方代码中的参数 0952befd5b7da358ad12fae3437515b1
<script>
	var _hmt = _hmt || [];
	(function() {
	  var hm = document.createElement("script");
	  hm.src = "https://hm.baidu.com/hm.js?0952befd5b7da358ad12fae3437515b1";
	  var s = document.getElementsByTagName("script")[0];
	  s.parentNode.insertBefore(hm, s);
	})();
</script>
2. 配置
./markdown-blog web --analyzer-baidu 0952befd5b7da358ad12fae3437515b1

谷歌

1. 访问 https://analytics.google.com 创建站点,获取官方代码中的参数 G-MYSMYSMYS
<script async="" src="https://www.googletagmanager.com/gtag/js?id=G-MYSMYSMYS"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'G-MYSMYSMYS');
</script>
2. 配置
./markdown-blog web --analyzer-google G-MYSMYSMYS

标题栏图标

默认读取与程序运行同一级目录的 favicon.ico 文件

导航排序

博客导航默认按照 字典 排序,可以通过 @ 前面的数字来自定义顺序

个人博客目录如下图

image

博客导航展示如下图

image

部署

Nginx 反向代理配置文件参考

HTTP协议

server {
    listen      80;
    listen [::]:80;
    server_name yourhost.com;

    location / {
         proxy_pass  http://127.0.0.1:5006;
         proxy_set_header   Host             $host;
         proxy_set_header   X-Real-IP        $remote_addr;
         proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
     }
}

HTTPS 协议(80端口自动跳转至443)

server {
    listen      80;
    listen [::]:80;
    server_name yourhost.com;

    location / {
        rewrite ^ https://$host$request_uri? permanent;
    }
}

server {
    listen          443 ssl;
    server_name     yourhost.com;
    access_log      /var/log/nginx/markdown-blog.access.log main;


    #证书文件名称
    ssl_certificate /etc/nginx/certs/yourhost.com_bundle.crt;
    #私钥文件名称
    ssl_certificate_key /etc/nginx/certs/yourhost.com.key;
    ssl_session_timeout 5m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
    ssl_prefer_server_ciphers on;

    location / {
         proxy_pass  http://127.0.0.1:5006;
         proxy_set_header   Host             $host;
         proxy_set_header   X-Real-IP        $remote_addr;
         proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
     }
 }

升级

  1. 下载最新版 release

  2. 停止程序,解压替换 markdown-blog

  3. 重新启动程序

开发

  1. 安装 Golang 开发环境

  2. Fork 源码

  3. 启动 web服务

    运行之后访问地址 http://localhost:5006,API请求会转发给 markdown-blog 程序

    make run
    
  4. 编译

    bin 目录生成当前系统的压缩包,如:markdown-blog-v1.1.0-darwin-amd64.tar

    make
    
  5. 打包

    package 目录生成当前系统的压缩包,如:markdown-blog-v1.1.0-darwin-amd64.tar

    make package
    
  6. 生成 Windows、Linux、Mac 的压缩包

    package 生成压缩包,如:markdown-blog-v1.1.0-darwin-amd64.tar markdown-blog-v1.1.0-linux-amd64.tar.gz markdown-blog-v1.1.0-windows-amd64.zip

    make package-all
    

意见反馈

  • 在项目中遇到问题可以在 issues 中找找答案或者直接提问
  • 有任何建议和想法,可以在 discussions 中发起讨论

赞助商

授权许可

本项目采用 MIT 开源授权许可证,完整的授权说明已放置在 LICENSE 文件中。