8  site项目

本章将总结Quarto的建站流程技术,重点比照blogdown建站流程。

8.1 域名关系

首先,域名提供可以是如下三种之一:

  • 付费购买cloudflare域名:例如huhuaping.com。优点在于体现自己设计的标签,统一识别,方便好记。在此基础上可以添加子域名,例如:book.huhuaping.comfunds.huhuaping.com

  • 使用netlify提供的二级子域名:xxx.netlify.app。优点是免费不操心。缺点一是只能使用二级子域名,很多人都使用;二是不方便记忆和宣传。

  • 自建服务器域名:自己映射[域名]给相应[ip]。优点是自己灵活管理服务器内容,可扩展性强;缺点是维护技术门槛和维护费用都会比较高。

其次,平台之间可以相互映射指定的域名,也即域名映射。

  • 例如:netlify平台二级子域名huhuaping.netlify.app,可以映射到cloudflare平台的子域名site.huhuaping.com

  • 又例如:自建服务器的ip地址[176.241.115.xx],可以创建A类域名(例如www.huhuaping.com),托管在cloudflare平台上,从而实现域名解析。

8.2 netlify平台

发布网站到netlify简单地有两种方式:

  • 第一,直接使用publish command:quarto publish netlify,这将会把_site/文件夹上传到netlify从而站点发布。

  • 第二,通过github进行触发式站点发布。需要管理netlify与R项目的github仓库。一旦R project进行了git push,则触发netlify的网站渲染。

测试R运算,显示计算结果。此时使用Quarto Netlify Build Plugin来调用netlify的server渲染。

测试更新Quarto Netlify Build Plugin到0.06版本,测试失败。官方说这是netlify的一个bug,目前不知道何时能解决。

尽量本地运行R代码,并保存结果到freeze。

尽量避免使用github action,这样会在CL远端执行R代码,因为这种运行很难保证未来持续性和可运行。

8.2.1 上传站点到netlify

基本流程:

  • 登陆netlify,创建自己的站点(选择add new site \(\Rightarrow\) deploy manually \(\Rightarrow\) 拉动上传文件夹_book_site)。修改为可读的域名地址,获得新建站点的id域名

  • 设置_publish.yml文件(参看),正确配置站点的id域名

  • 本地render以及终端命令publish。

注记

(1)目前暂时不明确,这种上传模式是完全覆盖还是增量覆盖,前者可能对较大站点不友好,上传速度有待考证。

(2)quarto publish netlify默认是需要重新render然后再publish。因此,最好在本地render好(确保页面正确),然后将_book/直接上传到netlify,终端命令如下:

```{sh}
quarto publish netlify --no-render
```

(3)注意render时带来的中间产物(.md.pyhtml、对应文件夹等)。无论是Rstudio界面下”Build” > “Render Book”进行本地render,还是使用终端命令quarto publish netlify,一旦render不成功,或者耗时过长,那么在本地都会产生中间产物。如果不及时处理,那么这些中间产物会对版本控制(git)带来麻烦!

8.3 混合项目结构

有时候,我们希望得到一个“全能型”的网站。对于多种独立但又有联系的几个项目任务,期望能最后一起登台亮相,展现在一个网站中。

例如,quarto book方式独立进行一本英文书编译项目”book-en”;同时还以quarto book方式独立进行着中文书版本翻译项目”book-chn”;以及其他配套的独立项目”proj01”、“proj02”等。然后我们希望把它们全部“拟合”在一个quarto website的站点项目之下:

提示

需求场景:网站里直接包含多种quarto项目类型(website、book)

(1)导航栏1,《英文版book》,文件夹路径”book-en/“,类型为type: book

(2)导航栏2,《中文版book》,文件夹路径”book-cnn/“,类型为type: book

(3)导航栏,项目project1,文件夹路径”proj01/“, 类型为post

(3)导航栏,项目project2,文件夹路径”proj02/“, 类型为post

这当然是一种无可指摘现实需求,而且也展示了迫切性,因为随着关联性项目越来越多,东奔西突多面开工,很快就容易手慢脚乱而产生“迷失感”。

以上的建站诉求尽管不能算作“伪需求”,但起码也是不可取的“想象路线”。

实际上,地球上的其他某个人也提出了类似的需求,但被告知目前仅仅在Quarto架构下是无法实现的(其实也是没有必要如此操作的,参看Nesting a book into a website)。

下面我们从合理性、稳定性、易维护性角度等原则理清正确建站逻辑:

  • 合理性原则:最终的综合建站仅作为“展示窗口”,内容结构越简单则站点呈现的信息越合理。

  • 稳定性原则:多个关联性项目,既然被独立分开,应该就已经保持了足够的区分性,因此减少复杂关联可以保持各个项目更好的稳定性。

  • 易维护性原则:多个关联性项目,独立开发和运行,能更好地实现细颗粒度的维护,与常规工作惯例相匹配(各个项目独立的改进和修补),尤其是方便git流程迭代管理。

因此,正确的建站逻辑是:

  • 独立迭代开发各个关联性项目,保持其独立性

  • 尽量减少综合性主站的复杂性,而是更多地进行外部引用(href: xxx.com)

8.4 Quarto扩展

8.4.1 Font Awesome

Quarto扩展Font Awesome extension,可以方便地调用一些网络图标(Font Awesome icon )。

首先,需要再Quarto项目根目录下用terminal命令安装:

$ quarto add quarto-ext/fontawesome

然后,使用语法见下面一些有趣的展示:

  • \{\{< fa brands apple >\}\} 显示为

  • \{\{< fa calendar >\}\} 显示为

  • \{\{< fa user-doctor >\}\} 显示为

  • \{\{< fa solid file-pdf >\}\} 显示为

  • \{\{< fa regular file-pdf >\}\} 显示为

当然,需要注意的是:

  • Font Awesome图标可以同时用于HTML和PDF输出格式。

  • 图标并不是完全免费使用。免费Font Awesome图标可以通过如下网址检索: https://fontawesome.com/search?m=free