在GitHub Pages上用Jekyll建静态网页，并且在macOS上预览

发表于 | 分类于

目标

COVID-19的项目需要建立一个展示网页，我的思路是建立一个静态网站，然后用脚本来实现自动更新数据。一通调查后我打算采用以下方式实现：

  • 静态网站：GitHub Pages + Jekyll
  • 表格和图：Plotly、百度的pyecharts（待定）、MATPLOTLIB+mpld3（待定）
  • 在macOS本地预览
  • 可以使用Mathjax编写数学式子

静态网站：GitHub Pages + Jekyll

在macOS本地预览

首先需要安装Ruby和Jekyll，参考：https://jekyllrb.com/docs/installation/macos/

Install Command Line Tools

First, you need to install the command-line tools to be able to compile native extensions, open a terminal and run:

1
xcode-select --install

Install Ruby

Jekyll requires Ruby > 2.5.0. macOS Catalina 10.15 comes with ruby 2.6.3, so you’re fine. If you’re running a previous macOS system, you’ll have to install a newer version of Ruby.

Check your Ruby setup:

1
2
3
4
$ which ruby 
/usr/bin/ruby
$ ruby -v
ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]

Install Jekyll

Now all that is left is installing Bundler and Jekyll.

Local Install

1
gem install --user-install bundler jekyll

and then get your Ruby version using

1
2
ruby -v
ruby 2.6.3p62 (2019-04-16 revision 67580) [universal.x86_64-darwin19]

Then append your path file with the following, replacing the X.X with the first two digits of your Ruby version.

1
echo 'export PATH="$HOME/.gem/ruby/X.X.0/bin:$PATH"' >> ~/.bash_profile

To check that your gem paths point to your home directory run:

1
gem env

And check that GEM PATHS: points to a path in your home directory.

在GitHub repo中初始化Jekyll site

1
2
3
4
5
$ cd REPOSITORY-NAME
# Changes the working directory

$ git checkout gh-pages
# Switches to the gh-pages branch

接下来初始化Jekyll site。在此之前，需运行以下命令，否则会报错：”Could not locate Gemfile or .bundle/ directory”

1
2
3
4
5
6
7
# 以下三条命令参考：https://stackoverflow.com/questions/59913903/how-to-run-bundle-exec-jekyll-new
# This command is necessary to create the Gemfile:
$ bundle init
# and this one to populate it with Jekyll:
$ bundle add jekyll
# so that when I re-ran my setup command, it worked:
$ bundle exec jekyll 4.1.1 new .

接下来参考：https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll，从第7个point开始：
To create a new Jekyll site, use the jekyll new command, replacing VERSION with the current dependency version for Jekyll. For more information, see “Dependency versions“ on the GitHub Pages site.

1
2
$ bundle exec jekyll VERSION new .
# Creates a Jekyll site in the current directory

打开Gemfile，注释掉

1
gem "jekyll", "~>4.1"

添加

1
gem "github-pages", group: :jekyll_plugins

接下来参考：https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll

1
2
3
4
5
6
7
8
9
10
11
12
# Run your Jekyll site locally.
$ bundle exec jekyll serve
> Configuration file: /Users/octocat/my-site/_config.yml
>            Source: /Users/octocat/my-site
>       Destination: /Users/octocat/my-site/_site
> Incremental build: disabled. Enable with --incremental
>      Generating...
>                    done in 0.309 seconds.
> Auto-regeneration: enabled for '/Users/octocat/my-site'
> Configuration file: /Users/octocat/my-site/_config.yml
>    Server address: http://127.0.0.1:4000/
>  Server running... press ctrl-c to stop.

注意看安装时的提示，不要直接copy命令。

push到GitHub

没什么特殊的，新建.gitignore文件，添加：

1
2
.DS_Store
vender/

然后

1
2
3
$ git add .gitignore Gemfile Gemfile.lock _site/* .bundle/*
$ git commit -m 'test for submittion'
$ git push

在GitHub Pages上显示交互式绘图（.html文件）

参考1

参考：https://qastack.cn/programming/60513164/display-interactive-plotly-chart-html-file-on-github-pages

如果您在GitHub页面网站上使用Jekyll。

准备数据：

1
2
3
4
5
6
import plotly.graph_objects as go

labels = ['Oxygen','Hydrogen','Carbon_Dioxide','Nitrogen']
values = [4500, 2500, 1053, 500]
fig = go.Figure(data=[go.Pie(labels=labels, values=values)])
fig.show()

生成HTML文件：

1
2
3
import plotly.io as pio

pio.write_html(fig, file='figure.html', auto_open=True)

上载figure.html文件并将其提交到_includes站点存储库根目录中的文件夹。

现在，如果您正在使用markdown创建帖子，则可以使用include标记，并figure.html在帖子中调用如下内容：

1
{% include figure.html %}

将此行提交到.md文件_posts夹中的发布文件。检查结果。

参考2

https://plotly.com/chart-studio-help/embed-graphs-in-websites/

参考3

https://github.com/youyanggu/covid19_projections

实践

在实践中我的做法是：

  1. 在https://plotly.com/python/中找到想要的图，并用Python生成iframe和html
  2. 在markdown里用{% include iframe.html %}引用iframe，其中iframe.html文件保存在_includes文件夹里
    iframe.html内容例子：
    1
    2
    <iframe width="100%" height="1050" frameborder="0" seamless="seamless" scrolling="no" src="us-home1.html"></iframe>
    <iframe width="100%" height="1050" frameborder="0" seamless="seamless" scrolling="no" src="us-home2.html"></iframe>
    其中us-home1.html保存在根目录下，内容样例：https://raw.githubusercontent.com/youyanggu/covid19_projections/gh-pages/us-home1.html

plotly画图

参考：https://plotly.com/python/dropdowns/

Time Series Plot

参考：https://plotly.com/python/time-series/

Continuous Error Bands

参考：https://plotly.com/python/continuous-error-bars/

Sider controls

参考：https://plotly.com/python/sliders/

Maps

参考：

geojson下载地址：https://github.com/codeforamerica/click_that_hood/tree/master/public/data

Tips

Hiding the Plotly Logo on the Modebar

就是隐藏右上角的Plotly Logo

参考：https://plotly.com/python/configuration-options/#hiding-the-plotly-logo-on-the-modebar

Tips

改变网站主题颜色

参考：https://github.com/pages-themes/cayman/issues/12#issuecomment-612551239

I managed to change the colors by following the instructions on https://github.com/pages-themes/cayman#stylesheet. See below for an example of the style.scss file. if you don’t add the — lines then the colours won’t change.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
---
---

// Breakpoints
$large-breakpoint: 64em !default;
$medium-breakpoint: 42em !default;

// Headers
$header-heading-color: #fff !default;
$header-bg-color: #f39c12;
$header-bg-color-secondary: #e67e22;

// Text
$section-headings-color: #D35400;
$body-text-color: #606c71 !default;
$body-link-color: #1e6bb8 !default;
$blockquote-text-color: #819198 !default;

// Code
$code-bg-color: #f3f6fa !default;
$code-text-color: #567482 !default;

// Borders
$border-color: #dce6f0 !default;
$table-border-color: #e9ebec !default;
$hr-border-color: #eff0f1 !default;

@import "{{ site.theme }}";

注意：style.scss是指/assets/css/style.scss

修改网站样式

根据/_sass/jekyll-theme-cayman.scss在/assets/css/style.scss中修改。

例如修改网页内容宽度：
在/_sass/jekyll-theme-cayman.scss中查找到相关设置：

1
2
3
4
5
6
7
8
9
10
.main-content {
  // ...
  @include large {
    max-width: 64rem;
    padding: 2rem 6rem;
    margin: 0 auto;
    font-size: 1.1rem;
  }
  // ...
}

然后在/assets/css/style.scss中，在@import "{{ site.theme }}";后面添加：

1
2
3
4
5
6
.main-content {
@include large {
    max-width: 80rem;
    padding: 2rem 5rem;
  }
}

修改链接

问题

我在repo的gh-pages分支中储存网页代码，因此希望提交到github后，用https://username.github.io/project-name/打开index页面，随后点击about的button时，转到https://username.github.io/project-name/about。

而实际上，由于我的_layouts/default.html中代码为：

1
2
3
4
5
6
...
<a href="/" class="btn">Home</a>
<a href="/about" class="btn">About</a>
<a href="/#results" class="btn">Results</a>
<a href="/models" class="btn">Models</a>
...

因此在本地预览时：
index页面：127.0.0.1:4000/
about页面：127.0.0.1:4000/about

push到github上:
index页面：https://username.github.io/project-name/
about页面：https://username.github.io/about
于是about页面显示错误

而我将default.html代码改为：

1
2
3
4
5
6
...
<a href="/" class="btn">Home</a>
<a href="{{ site.github.repository_name }}/about" class="btn">About</a>
<a href="/#results" class="btn">Results</a>
<a href="{{ site.github.repository_name }}/models" class="btn">Models</a>
...

虽然push到github后可以正常显示，但是在本地预览时about的button就会失效。

解决方法

参考：https://github.com/jekyll/jekyll/issues/332#issuecomment-18952908

I finally figured out the trick, if you’re looking for a solution with the standard URL for GitHub Pages (username.github.io/project-name/). Here’s what to do:

In _config.yml, set the baseurl option to /project-name – note the leading slash and the absence of a trailing slash.

Now you’ll need to change the way you do links in your templates and posts, in the following two ways:

When referencing JS or CSS files, do it like this: {{ site.baseurl }}/path/to/css.css – note the slash immediately following the variable (just before “path”).

When doing permalinks or internal links, do it like this: {{ site.baseurl }}{{ post.url }} – note that there is no slash between the two variables.

Finally, if you’d like to preview your site before committing/deploying using jekyll serve, be sure to pass an empty string to the --baseurl option, so that you can view everything at localhost:4000 normally (without /project-name getting in there to muck everything up): jekyll serve --baseurl ''

This way you can preview your site locally from the site root on localhost, but when GitHub generates your pages from the gh-pages branch all the URLs will start with /project-name and resolve properly.

照着做就行了。

使用Mathjax编写数学式子

参考：

在实践中我的做法：

  1. 设置markdown引擎为kramdown，方法为在 _config.yml 里添加：
    1
    markdown: kramdown
  2. 在md文件开始输入代码：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    <head>
        <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
        <script type="text/x-mathjax-config">
            MathJax.Hub.Config({
                tex2jax: {
                skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
                inlineMath: [['$','$']]
                }
            });
        </script>
    </head>

然后就可以用$...$或者$$...$$编写数学式子，注意用$$...$$时前面需要空一行。

插入图片

正常插入图片：

1
![image demo](images/image_demo.png)

指定图片尺寸，kramdown支持指定图片属性：

1
![image demo](images/image_demo.png){:height="50%" width="80%"}

图片居中：

1
2
3
{:refdef: style="text-align: center;"}
![image demo](images/image_demo.png){:height="50%" width="80%"}
{: refdef}

参考：

Are Github pages created automatically in the fork of a repo which has a gh-pages branch?

参考：https://stackoverflow.com/questions/8587321/are-github-pages-created-automatically-in-the-fork-of-a-repo-which-has-a-gh-page

并不能自动创建可访问的github pages，需要：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ git checkout gh-pages 
Branch 'gh-pages' set up to track remote branch 'gh-pages' from 'origin'.
Switched to a new branch 'gh-pages'

$ git push -f origin HEAD^:gh-pages
Warning: remote port forwarding failed for listen port 52698
Total 0 (delta 0), reused 0 (delta 0)
To github.com:SITE5039/covid19.git
 + 388ef4c...94c03c3 HEAD^ -> gh-pages (forced update)
 
$ git push origin gh-pages:gh-pages
Warning: remote port forwarding failed for listen port 52698
Total 0 (delta 0), reused 0 (delta 0)
To github.com:SITE5039/covid19.git
   94c03c3..388ef4c  gh-pages -> gh-pages