Davinci可视化平台 —— Jekyll+Minimal Mistakes的用户手册工程本地打包发布

本文链接：https://blog.csdn.net/huzhenv5/article/details/104196806

Davinci 是一个 DVaaS（Data Visualization as a Service）平台解决方案，面向业务人员/数据工程师/数据分析师/数据科学家，致力于提供一站式数据可视化解决方案。

Davinci源码地址：
https://github.com/edp963/davinci
Jekyll中文文档地址：
http://jekyllcn.com/
Minmal Mistakes源码地址：
https://github.com/mmistakes/minimal-mistakes

Davinci源码大概分为三部分：

采用React的前端工程
采用Spring Boot的后端工程
采用Jekyll + Minmal Mistakes的文档工程，用来介绍Davinci的用户操作方法

本篇文章将介绍如何将Davinci源码中的文档部分抽离出来，打包成静态的网页部署到nginx上，下面开始介绍步骤：

笔者环境：
系统：Windows10 64位
Ruby：ruby 2.6.5p114 (2019-10-01 revision 67812) [x64-mingw32]
Davinci：davinci-0.3.0-beta.8

一，安装Ruby开发环境

由于文档工程采用Jekyll + Minmal Mistakes，本机需要先安装Ruby开发环境，笔者尝试过安装Ruby2.7.0，结果在安装工程依赖过程中报错，提示Ruby版本需要大于等于2.3，小于2.7，所以笔者又安装了2.6.5的版本；因此笔者建议大家也安装2.6.5的Ruby版本，安装方法请看笔者的另外一篇文章：windows10上配置Ruby开发环境

二，下载Davinci源码

Davinci的源码地址文章开头已经给出，直接下载zip包或者通过git命令克隆到本地均可。下载好后，根目录下的docs文件夹就是我们后面需要用到的文档工程，我们将docs文件夹放到IDE中，准备开发，笔者采用的IDE是VS Code

Davinci源码目录：
在这里插入图片描述

docs文件夹目录：
在这里插入图片描述

三，修改_config.yml文件

文档工程采用的jekyll框架，源码中的主题采用的是远程主题，即remote_theme，由于笔者尝试在打包生成静态网页的时候，网速十分缓慢导致失败，所以笔者将采用本地主题的方式，过程并不复杂，我们将_cnfig.yml中的remote_theme注释掉，将theme注释放开即可，修改后的_config.yml：

title: Davinci 用户手册
zh_masthead_title: 用户手册
baseurl: "/davinci"
logo: "assets/images/logo.svg"

theme: minimal-mistakes-jekyll
# remote_theme: "mmistakes/minimal-mistakes@4.16.5"
markdown: kramdown
minimal_mistakes_skin: "default"
plugins:
  - jekyll-feed
  - jekyll-include-cache

collections:
  docs:
    permalink: /:collection/:path
    output: true

DAVINCI_VERSION: 0.3
DAVINCI_VERSION_SHORT: 0.3

四，修改Gemfile

采用本地主题，需要添加相关的依赖，操作步骤：注释掉gem "github-pages", group: :jekyll_plugins；放开注释：gem "minimal-mistakes-jekyll"，并在后面加上逗号和版本号，minimal-mistakes-jekyll的版本号可以在_config.yml中看到：
在这里插入图片描述
修改后的Gemfile

source "https://rubygems.org"

# Hello! This is where you manage which Jekyll version is used to run.
# When you want to use a different version, change it below, save the
# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
#
#     bundle exec jekyll serve
#
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
gem "jekyll", "~> 3.8.3"

# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins

# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.6"
  gem "jekyll-include-cache"
end

# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
  gem "tzinfo", "~> 1.2"
  gem "tzinfo-data"
end

# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?

gem "minimal-mistakes-jekyll", "4.16.5"
# gem "github-pages", group: :jekyll_plugins

五，安装依赖

进入docs文件夹，在该路径下运行命令：

bundle install

在这里插入图片描述
等待依赖安装完成，安装完成之后会在docs根目录下生成一个Gemfile.lock文件

六，启动jekyll自带的serve

在docs路径下运行命令：

bundle exec jekyll serve

在这里插入图片描述
打开链接：http://127.0.0.1:4000/davinci/

七，修复free.min.js超时

进行到第6步的时候，其实就已经改的差不多，可以直接打包发布了，但是笔者打开chrome控制台的时候，发现有个free.min.js的请求超时，反正网页已经可以正常显示了，那么笔者就想着将这个请求去掉，不然看着碍眼
在这里插入图片描述
排错过程就不多说了，笔者直接上步骤了：

1，下载Minmal Mistakes源码

下载依赖中对应版本的Minmal Mistakes源码，下载链接在文章开头已经给出，本文是4.16.5的版本，以下载该版本为例，进入Minmal Mistakes的github地址后，进入release页面，找到对应的版本并下载：
在这里插入图片描述

2，复制源码中的`scripts.html`

下载好后，将源码中的_includes文件夹下的scripts.html文件复制到docs工程的_includes文件夹下

3，删除`scripts.html`中的一个引用

删除该html文件中的<script src="https://kit.fontawesome.com/4eee35f757.js"></script>这行引用
在这里插入图片描述
再运行bundle exec jekyll serve，访问http://127.0.0.1:4000/davinci/，发现报错已经不见了

八，打包

在docs路径下运行命令：

bundle exec jekyll build

在这里插入图片描述
打包完成后，再docs根目录会生成一个_site文件夹，就是用于部署的静态页面

注意：
bundle exec jekyll serve命令也会在根目录生成_site文件夹，但是该文件夹并不能拿到nginx去部署

九，nginx部署

上步打包生成的_site文件夹里的内容就是静态页面的内容

nginx如何部署静态网页的方法网上很多，这里就不赘述了，但是需要注意两点：

在nginx部署的时候，根目录的名称不能随意命名，需要和_config.yml文件的baseurl字段保持一致，默认是davinci
在跳转页面的时候，跳转链接的url上不带.html的后缀，直接部署在nginx上跳转会提示404的报错，所以在nginx上要配置下，对访问链接进行重写，加上.html后缀：

location /davinci/ {
    root   html;
    index  index.html index.htm;
    if (!-e $request_filename){
	    rewrite ^(.*)$ /$1.html last;
	    break;
	}
}