第 2 章 基于 blogdown 建立个人学术网站

NOTICE!

需要指出的是,由于涉及到的软件版本或技术在不断更新,请留意所使用的软件版本.现在是2022-07-31,从使用者角度,未来技术的发展一定会更加人性化、更加便利,因此,下面介绍的流程和技术细节可能会有变化!

这里介绍基于 Markdown 和 rmarkdown,用 blogdown、hugo、GitHub 和 netlify 搭建静态的 Blog 风格的个人学术网站技术.

其特色和优势:

  • 静态网页,速度快
  • 可用GitHub 保存内容,不需要搭建数据库,无须备份
  • 一旦搭建完成,就可在 Rstudio中,用 Markdown 或 rmarkdown 写作、操作、维护和管理网站
  • 用 netlify 注册、发布和托管你的网站,设置个性二级域名,免费、无限流量

提示:

以下内容可以分为两部分

1.Step0 - Step7 是利用 git 命令和 github 仓库创建、更新

2.本章最后一节的重要补充说明,给出了略过 git 和 github 仓库,创建、更新和部署网站的半自动化的方法.

2.1 Step 0: 准备工作

本文以 Microsoft Windows 操作系统为例,介绍安装和配置技术,其它操作系统类似.

如果事先系统中已经安装,请确保更新至最新版.

  1. GitHub 注册与配置

首先,大家要清楚 git 和 GitHub 的关系,自己去 Bing. 简单讲,git是一款开源、免费的版本控制软件，能够帮你更好的管理你的程序代码，github则是一个网站，这个网站是用git做版本控制的代码托管平台,在其上,可以帮助程序员之间互相交流和学习。

其次,Bing 完后别害怕,其实 Rstudio 已经有集成了 git 的 GUI 了,除非你另有打算,无须学会什么 add、commit、push、pull和 merge 等 git 命令就足以应付 blogdown 了,你只需在 Rstudio git GUI 上面用鼠标去点、点、点….,oh,这个我喜欢,但我不知道点哪儿….唉!

推荐安装 GitKraKen,去模拟 git 是怎么玩的,虽然这里不是必须的.

我们跳过 git,直接到 GitHub.

  • 打开GitHub 主页,注册你的个人账户(如果你已经有了,请绕过),找到如下页面
  • 在上述页面中, 点击右上角的new创建一个个人网站专用仓库(repository) 参考如图所示,填写好你的 repository name、Description,默认选择 Public,选择复选框 add a README file,其它就默认好了,最后,点击 Create repository 就创建好用于保存网站的repository了.
  • 转到你新建的 repository 页面,点击右上角的code按钮,点击右侧裁剪版图标,copy 显示的新存储库的远程网址 URL,后面在设置 Rstudio 时要用到
  • 基于安全考虑,GitHub 官方在 2020 年 7 月宣布从 2021 年 8 月 13 起,必須透过令牌(token)机制进行 git 的相关操作,以取代用户账户和密码。请参考此处指引申请你的 GitHub 用户令牌并妥善保管好,后面要用到!
  1. Rstudio 的配置

打开已安装好的 Rstudio,进行一些简单配置.

  • Tools -> Global Options -> Sweave -> Weave Rnw files using: knitr
  • Tools -> Global Options -> Sweave -> Typeset LaTex into PDF using: XeLaTeX

  • Tools -> Global Options -> Git/SVN -> Git executable: (安装好 git 后，打开这里应该就可以看到 git 的路径了)

注意:其上的SSH RSA key,当在 Rstudio 中进行 git 操作出现问题时,可能需要创建 key,并利用其去 github 中进行必要的设置,请参见码农家园.

  1. 安装 blogdown 和 hugo

在线安装 blogdown.打开 Rstudio,在 R 的终端窗口命令提示符”>“下输入:

> install.packages('blogdown')

这一过程通常应该比较顺利,如果有问题可以尝试安装开发版(前提是安装了 devtools扩展包,可通过install.packages("devtools")安装):

> devtools::install_github("rstudio/blogdown")

在线安装 hugo.同上,在 R 的终端窗口命令提示符”>“下输入:

> blogdown::install_hugo()

限于网络速度等原因, hugo 在线安装可能会无法安装成功. 解决的办法是,点击此处下载,解压后发现只有一个文件hugo.exe,把其放在一个目录下,然后在 R 的终端窗口命令提示符”>“下输入:

> blogdown:::install_hugo_bin("d:/hugo.exe") # 这里是三个冒号,注意更改你存放 hugo.exe 的真实路径

macOS 中的安装命令有所不同,例如:

> blogdown:::install_hugo("./downloads/hugo_0.87.0_macOS-64bit.tar.gz")
  1. hugo 的版本控制问题

Hugo 变化很快——新的功能被添加,原有的功能被取消.如果你有一个以上的 Hugo 版本,就容易出现问题,这可能会导致您在调试为什么上个月可以构建的站点现在不能构建.

blogdown现在可以把你的网站项目固定在一个特定的hugo版本上,你可以使用以下命令来查找所有本地安装的 Hugo 版本:

> blogdown::find_hugo('all')

你可能看到类似如下的输出

[1] "/Users/alison/Library/Application Support/Hugo/0.54.0/hugo"
[2] "/Users/alison/Library/Application Support/Hugo/0.71.1/hugo"
[3] "/Users/alison/Library/Application Support/Hugo/0.78.2/hugo"
[4] "/Users/alison/Library/Application Support/Hugo/0.79.0/hugo"
[5] "/usr/local/bin/hugo"

如果需要,你可以针对特定的网站项目,在其中的.Rprofile使用

options(blogdown.hugo.version = "0.79.0")

来指定使用 hugo 的版本,重新启动 R 即刻生效.注意,如果你使用 Netlify 部署网站,需要确保 Netlify 用来建立你的网站的 Hugo 版本也与你的本地版本相匹配.

你也可以定期清理一下不再使用的 本地hugo版本.要做到这一点.请使用:

> blogdown::remove_hugo()

按照屏幕提示操作即可.

如果你想更新 hugo,请使用命令

> blogdown::install_hugo()

安装一个新版本或一个特定的版本.默认情况下,它将安装最新的可用版本.

2.2 Step 1: 基于GitHub 仓库创建网站项目

关闭并重新启动 Rstudio.

前面只是在 GitHub 上创建了远程存储库.为了在我们的计算机上制作一个可以实际工作的本地副本,我们将把这个存储库克隆到一个新的 RStudio 项目中.这将允许我们在两个地点之间进行同步: 您的远程 GitHub和您的本地文件夹.

打开 RStudio 创建一个新的项目,在那里将存储您的网站文件 - File -> New Project -> Version Control -> Git

把前面复制的存储仓库的URL粘贴到 Repository URL方框内,意味着告诉 RStudio 在GitHub上的哪个仓库位置创建这个新项目, Project directory name应该自动就生成了,再选择一个合适的文件夹存放,最后点击Create Project完成项目创建.

至此,远程 github 上的储存库与本地网站项目建立对应.

2.3 Step 2: 基于blogdown创建网站框架

打开 Rstudio,在 R 的终端窗口命令提示符”>“下输入:

> library(blogdown)
> new_site(theme = "yihui/hugo-xmin")

或

> blogdown::new_site(theme = "yihui/hugo-xmin")

你会看到类似的运行输出

至此,基于谢益辉给出的hugo 主题 模版hugo-xmin的网站框架初步建成了,请仔细阅读这些输出内容后,让我们输入y来启动服务并预览所建网站.

应该有一点小激动了？现在,在 RStudio的 Viewer 标签窗口就看到了由 hugo-xmin 定制的网站页面了.

点击Viewer 标签下的图标”Show in new window”即可跳转到普通浏览器窗口中预览.

至此,我们建立的网站可以随时本地渲染和刷新了.方法是在终端命令行窗口输入

> blogdown:::serve_site()

或点击Addins在其下拉菜单

点击Serve Site.

注意可能会提示安装若干 R包例如 shiny、miniUI 等,点击 yes 安装就行了.如果网页中的数学公式不能正常显示,请安装 R 的扩展包xaringan,以保证网页的 mathjax.js 正常渲染.

> install.packages("xaringan")

关于 Hugo 主题

Hugo 是一个静态网站生成器,最简单的方法是利用事先构建好的主题,主题控制着页面的整体外观和功能,前面我们就是使用了 hugo-xmin 主题. 值得庆幸的是,我们可以不劳而获地免费使用大量的hugo theme.

理论上,选择喜欢的主题后,需要弄清楚这个主题的Github用户名和储存库的名字,然后通过命令 进行安装,或者在创建博客的时候给new_site()传递theme参数.

点击一个主题进去后,在其网页地址栏找到其Github用户名和储存库的名,下载安装到本地,例如

> blogdown::install_theme("luizdepra/hugo-coder")

之后,在创建一个新站点时,通过传递主题参数使用该主题

> blogdown::new_site("luizdepra/hugo-coder")

但是,过于复杂的hugo主题,在部署的时候可能出现问题,功能冗余也导致维护困难.总之,除非必要,慎用复杂主题,够用就好.通常要围绕设定好的网站建设的目的和目标,进行网站风格、功能选择合适的主题!

对于搭建个人网站，曾经有一句经典的忠告：

永远不要使用复杂的模板，否则总有一天会掉入网站迁移漩涡，甚至万劫不复的境地。

—nobody

Keep it simple, but not simpler!

2.4 Step 3: 个性化修改主题模版

利用已有主题模版初步建立了网站,但通常需要对主题模版进行个性化改造和定制.

主题模版信息分布在网站文件夹中的相关文件中,找到并修改.需要注意的是

  • 你要清楚为什么要改动,以及正确的做法
  • 要做好备份,一旦修改后渲染有问题,要确保能够回溯

2.5 Step 4: 上传本地内容到 GitHub仓库

在本地,把网站主题模版调整好,并确保本地渲染无误后,就需要把其上传到 GitHub 上,做好用 netlify 自动化部署你的网站的准备.

首次上传之前,要确保以下工作的完成:

1.为避免不必要的文件或目录上传到 GitHub 仓库,要设置 .gitignore文件,方法是打开 Rstudio找到的Files标签，点击项目所在文件夹中.gitignore文件，例如改成下面这样

.Rproj.user
.Rhistory
.RData
.Ruserdata
/public/
/static/figures/

2.在上传之前,blogdown 的检查功能可以帮助你诊断和防止你的网站出现构建问题.检查将帮助您识别已知的问题，并提供确信无疑的建议，以指导您成功.共有 5 各检查命令:

  • blogdown::check_config(): 检查配置文件(config.yaml 或 config.toml
  • blogdown::check_gitignore():检查 Git 时是否不正确地忽略了必要的文件
  • blogdown::check_hugo(): 检查hugo安装和版本可能出现的问题
  • blogdown::check_netlify():检查一些重要的 Netlify 配置netlify.toml
  • blogdown::check_content() :检查内容文件中可能存在的问题.比如 YAML元数据的有效性,一些带有未来日期和草稿的帖子,或者 Rmarkdown 未渲染的文章 等

一般而言,config.yaml或config.toml、.gitignore 、netlify.toml的内容,只需在建站之初设置.原则上,上传文件或目录,以及框架下页面内容没有变化,可不必修改和理会.

而每次新建或修改了内容,往往最好要检查其内容是否存在问题,也即进行check_content()检查.

最后指出命令

blogdown::check_site()

将同时运行以上所有 check_*()命令.

NOTICE!

这项检查很重要,是成功上传到 GitHub 和用 Netlify 部署的关键!

3.最后,使用

blogdown::server_site()

查看网站本地渲染是否成功.

做好上述准备工作之后,可以进行上传 GitHub 仓库的工作了,方法是:

  • 在Rstudio点击 git标签,手动勾选(Staged)要上传的文件,点击commit按钮 会弹出一个窗口,填写好 commit message 点击commit按钮
  • 待commit结束后,点击这个窗口右上角的push按钮,将本地文件上传到Github.

2.6 Step 5: 使用 Netlify部署网站

就要大功告成了.部署网站有很多种方式,比如Netlify、Github、GitLab等,这里使用Netlify进行部署.

  • 注册 netlify

打开其注册页面,点击右上角Sign up,然后直接在 Sign up with one of the following: 下面选择 GitHub,即用GitHub 注册.

以后,就可以直接用选GitHub 进行登录.

  • 绑定 GitHub
  1. 登录进 netlify 后,点击导航栏Sites,再点击右上角New site from Git

  1. 再点击下面的Github

3. 再选择 GitHub 上的网站仓库 4. 等待片刻后,出现 5. 点击options -> Edit site name,设置网站的二级域名 最终就是这个样子了 打开一个浏览器,输入 http://hbsun.netlify.app.

Oh, amazing!

2.7 Step 6: 配置你的网站

接下来,可以使用 css、js 等进一步完善你的网站: 增加功能,雕刻风格……

关于修改主题模版忠告:

劝君更进一杯酒，模板莫要闲折腾!

—— Somebody

Done!

Doone!!

Dooone!!!

….

2.8 Step7:开始工作

首先准备一杯咖啡……,然后,优雅地打开 Rstudio 进入你的网站项目……

  • 新建内容

在Addins下拉菜单中,点击New Post,弹出

其中,Filename处会自动帮你填写为Title处的内容,Filename和Slug还是建议使用字母,尤其是Filename,如果文中不需要用到 R 语言的代码计算结果生成图表的话，Format处就选择Markdown格式,这可以省去一些系统生成的步骤.点击Done就会在/content/post文件夹下面生成一个文件名类似为2000-01-01-my-first-blog.Rmd这样的文件了,content 文件夹下面的文件就是所有你的所有文章了,这个时候就可以在弹出的编辑窗口中输入内容了,保存后在本地 Viewer 中即可看到刚刚新建的文件及其变化.

  • 修改内容

也可能今天没有新的东西要写,而是要对昨天上传到网站的某个内容进行修改、补充完善.

点击Files标签,会显示你的本地网站项目文件夹中的所有文件,找到你准备修改的文件单击打开,完事后保存即可.

请注意,这些工作都是在本地完成.

  • 更新网站

把写好或修改好的文章 update 到线上.

点击Git标签，点击commit会弹出一个窗口(如下图所示),填写好 commit message 点击commit按钮,再点击这个窗口右上角的push按钮,这样就可以把本地内容更新线上.

稍等片刻,打开你的个人主页http://hbsun.netlify.app,就可以看到网站已经更新.

2.9 重要补充说明

折腾了半天,其实,这个补充说明来的太晚了,但是,早有早的好处,晚有晚的道理!

前面讨论的是在 Rstudio 中,基于 git 在 netlify自动化部署网站的技术和流程.如果你对 git 和 github ,亦或对 netlify 设置不熟悉,或在Rstudio 中使用 git 遇到问题,无法实现前述git(commit,push)-github(repository)-netlify的网站自动化部署流程,我们可以略去 git 和 github 这一环节,在 Rstudio 中创建或更新网站内容后,在 netlify 中手动、快速部署你的网站.

具体流程如下:

1.基于 blogdown 创建、更新网站

2.运行

blogdown::check_site()

和

blogdown::server_site()

确保网站没有需要完善的地方,以及本地渲染、预览成功后,使用命令

blogdown::build_site()

命令,你应该看到在第一次运行该命令前一直空着的项目根目录下的目录public 生成了一系列文件,请注意切勿编辑此目录中的文件.

3.手动拖拽public目录到 https://app.netlify.com/drop 指定区域,稍等片刻后,它会分配一个随机子域的形式 random-word-12345.netlify.app,这就是你的网址,网站已经部署完毕,在浏览器打开,就可以看到你的网站了!

4.用前述办法,登录已经注册过的 netlify,把随机二级子域名改为你想要的,比如https://hbsun.netlify.app.

5.同样从您的帐户，您可以通过在本地进行更改来更新您现有的网站，然后 blogdown::build_site()重建你的网站,在 Netlify 的“部署”选项卡，找到特殊的区域,在其中拖进您更新 过的public文件夹,片刻后,即可更新已部署的网站。

OK,it is too……let’s breaking…….