在 Docker 中运行 Quarto Markdown #
Quarto (opens new window) 是一个基于 Markdown 文件生成 PDF、Word 文档、HTML 网页、ePub 文件、幻灯片等多种输出的工具。
使用 Quarto，您可以将任何 Markdown 内容呈现为新的 PDF 文件。
Quarto支持各种功能，还可以添加来自社区的扩展，使其成为任何希望生成文档的人的实用工具。
个人而言，我多年来没有使用过类似Word类型的文字处理器；也没有使用过PowerPoint，甚至我自己都不记得上一次使用是什么时候了。
尽管如此，我生成了大量文档和幻灯片。我用Markdown写所有内容，然后从相同的内容生成PDF或幻灯片。
直到最近，我一直在使用pandoc (opens new window)，但是，花时间了解Quarto后，发现它更加强大。
像这个博客上一样，您不会以传统方式安装Quarto。相反，您将创建我们自己的Docker镜像。
让我们开始 #
一如既往，您现在将为实验创建一个临时文件夹。请启动Linux shell并运行 mkdir -p /tmp/docker-quarto && cd $_。
创建您自己的Docker镜像 #
创建一个名为Dockerfile（没有扩展名）的新文件，具有以下内容：
# 基于https://github.com/analythium/quarto-docker-examples/blob/main/Dockerfile.base
# 要下载和使用的Quarto版本号
ARG QUARTO_VERSION="1.4.529"
ARG OS_USERNAME=quarto
ARG UID=1000
ARG GID=1000
FROM eddelbuettel/r2u:20.04
# librsvg2-bin用于在呈现PDF文件时允许SVG转换（将安装rsvg-view二进制文件）
RUN set -e -x && \
apt-get update && apt-get install -y --no-install-recommends \
pandoc \
pandoc-citeproc \
curl \
gdebi-core \
librsvg2-bin \
python3.8 python3-pip \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
RUN set -e -x && \
install.r shiny jsonlite ggplot2 htmltools remotes renv knitr rmarkdown quarto
# 下载并安装Quarto
ARG QUARTO_VERSION
RUN set -e -x && \
curl -o quarto-linux-amd64.deb -L https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-amd64.deb \
&& gdebi --non-interactive quarto-linux-amd64.deb \
&& rm -f quarto-linux-amd64.deb
# 应该为用户执行；如果为root用户执行，则不起作用（quarto将说“未安装tinytex”）
ARG OS_USERNAME
ARG UID
ARG GID
RUN set -e -x && \
groupadd -g $GID -o "${OS_USERNAME}" && \
useradd -m -u $UID -g $GID -o -s /bin/bash "${OS_USERNAME}"
USER "${OS_USERNAME}"
# 安装诸如tinytex之类的工具，以允许转换为PDF
RUN set -e -x && \
quarto install tool tinytex --update-path
RUN set -e -x && \
printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr update" \
&& ~/.TinyTeX/bin/x86_64-linux/tlmgr update --self --all && \
~/.TinyTeX/bin/x86_64-linux/fmtutil-sys --all
# 有关说明，请参阅https://github.com/rstudio/tinytex/issues/426
RUN set -e -x && \
printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr install for a few tinyText packages (needed for PDF conversion)" \
&& ~/.TinyTeX/bin/x86_64-linux/tlmgr install fvextra footnotebackref pagecolor sourcesanspro sourcecodepro titling
USER root
RUN set -e -x && \
mkdir -p /input
USER "${OS_USERNAME}"
WORKDIR /
以上操作完成后，请运行 docker build -t cavo789/quarto .，第一次可能需要大约三分钟时间，之后您将获得自己的Docker镜像：
❯ docker build -t cavo789/quarto .
[+] Building 208.2s (13/13) FINISHED docker:default
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 2.08kB 0.0s
=> [internal] load metadata for docker.io/eddelbuettel/r2u:20.04 3.4s
=> CACHED [ 1/10] FROM docker.io/eddelbuettel/r2u:20.04@sha256:133b40653e0ad564d348f94ad72c753b97fb28941c072e69bb6e03c3b8d6c06e 0.0s
=> [ 2/10] RUN set -e -x && apt-get update && apt-get install -y --no-install-recommends pandoc pandoc-citeproc curl gdebi-core librsvg2-bin python3.8 47.6s
=> [ 3/10] RUN set -e -x && install.r shiny jsonlite ggplot2 htmltools remotes renv knitr rmarkdown quarto 27.2s
=> [ 4/10] RUN set -e -x && curl -o quarto-linux-amd64.deb -L https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.529/quarto-1.4.529-linux-amd64.deb && gdebi - 12.1s
=> [ 5/10] RUN set -e -x && groupadd -g 1000 -o "quarto" && useradd -m -u 1000 -g 1000 -o -s /bin/bash "quarto" 0.5s
=> [ 6/10] RUN set -e -x && quarto install tool tinytex --update-path 23.0s
=> [ 7/10] RUN set -e -x && printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr update" && ~/.TinyTeX/bin/x86_64-linux/tlmgr update --self --all && ~/.TinyTeX/bin/x86_64-linux/fm 77.9s
=> [ 8/10] RUN set -e -x && printf "\e[0;105m%s\e[0;0m\n" "Run tlmgr install for a few tinyText packages (needed for PDF conversion)" && ~/.TinyTeX/bin/x86_64-linux/tlmgr 11.7s
=> [ 9/10] RUN set -e -x && mkdir -p /input 0.5s
=> exporting to image 4.0s
=> => exporting layers 4.0s
=> => writing image sha256:fe1d20bd71a66eb574ba1f5b35c988ace57c2c30f93159caa4d5de2f8c490eb0 0.0s
=> => naming to docker.io/cavo789/quarto 0.0s
What's Next?
View summary of image vulnerabilities and recommendations → docker scout quickview
之前的指令 docker build -t cavo789/quarto . 创建了一个名为 cavo789/quarto 的镜像。您当然可以选择不同的名称，不会对镜像产生任何影响。
您可以快速检查镜像的大小；虽然很大，但除非内存/磁盘空间非常有限；否则这并不是什么大问题。
❯ docker image list | grep quarto
cavo789/quarto latest fe1d20bd71a6 10 minutes ago 2.14GB
使用Quarto并生成PDF文件 #
在您的 /tmp/docker-quarto 文件夹中创建一个名为 test.md 的新文件，内容如下：
# 什么是Quarto？像我五岁解释一样
想象一下，您想写一个故事或报告，但是不使用花哨的计算机程序，而是使用纯文本。这有点像Markdown，一种简单的语言，让您格式化文本而不会变得过于复杂。
现在，Quarto就像是一个超级强大的写作工具，它理解Markdown，并还可以帮助您用不同语言编写代码，比如R或Python。就像在写作过程中有一个助手，让事情变得更容易更有趣。
因此，如果您想创建文档、演示文稿，甚至是书籍，Quarto和Markdown可以成为您的朋友。它们将帮助您组织思绪，添加很酷的功能，甚至与世界分享您的作品。
以上是Markdown内容的翻译，希望对您有所帮助。 现在，回到您的Linux控制台，将该文件转换为pdf。请参考Quarto (opens new window)的官方文档获取更详细的信息。
要转换为PDF，执行的指令是 quarto render test.md --to pdf。但由于您正在使用来自Docker镜像的Quarto，指令变为 docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf。
作为提醒，使用的Docker运行命令通常是相同的：
-it以交互方式启动Docker，这将允许容器中运行的脚本向您请求一些提示，例如，--rm要求Docker在脚本执行完毕后终止并删除容器（否则您将有很多已退出但未删除的Docker容器；您可以检查是否使用--rm标志然后在控制台上运行docker container list），-v ${PWD}:/input将当前文件夹与Docker容器中的名为/input的文件夹共享，-w /input告诉Docker，容器中的当前目录将是/app文件夹，-u $(id -u):$(id -g)请求Docker重用我们的本地凭据，这样当在容器中更新/创建文件时，文件将归您所有，- 然后
cavo789/quarto这是您的Quarto Docker镜像的名称，最后， quarto render test.md --to pdf即容器内要执行的命令行。
因此，在您的控制台上运行 docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf，进行PDF转换。
❯ docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf`
pandoc
to: latex
output-file: test.tex
standalone: true
pdf-engine: xelatex
variables:
graphics: true
tables: true
default-image-extension: pdf
metadata
documentclass: scrartcl
classoption:
- DIV=11
- numbers=noendperiod
papersize: letter
header-includes:
- '\KOMAoption{captions}{tableheading}'
block-headings: true
Rendering PDF
running xelatex - 1
This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex)
restricted \write18 enabled.
entering extended mode
running xelatex - 2
This is XeTeX, Version 3.141592653-2.6-0.999995 (TeX Live 2023) (preloaded format=xelatex)
restricted \write18 enabled.
entering extended mode
Output created: test.pdf
向Quarto添加 --log-level warning CLI参数，要求它仅显示警告（和错误）消息。非必要输出将被隐藏，保持清洁的控制台。因此要使用的新命令是 docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to pdf --log-level warning。
使用Quarto生成HTML文件 #
简单地修改 --to 参数，将 pdf 替换为 html 并运行命令：docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to html --log-level warning。
现在，您的目录中有一个 test.html 文件。
使用Quarto生成revealjs幻灯片 #
这次，--to 参数应设置为 revealjs：docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to revealjs --log-level warning。
打开 test.html 文件，您将看到这个：
现在您只有一张幻灯片。重新打开 test.md 文件，并插入 幻灯片分隔符，可以使用 ---- 语法完成：
# 什么是Quarto？用五岁孩子的方式解释
想象一下，您想写一个故事或一份报告，但是不使用花哨的计算机程序，而是使用纯文本。这有点像Markdown，一种简单的语言，允许您格式化文本而不会变得太复杂。
----
现在，Quarto就像一个超级强大的写作工具，它理解Markdown，还可以帮助您使用不同语言编写代码，比如R或Python。这就像在写作过程中有一个助手，使事情变得更容易和更有趣。
----
因此，如果您想创建文档、演示文稿，甚至书籍，Quarto和Markdown可以成为您的朋友。它们将帮助您组织思绪，添加很酷的功能，甚至与世界分享您的作品。
重新运行 docker run -it --rm -v ${PWD}:/input -w /input -u $(id -u):$(id -g) cavo789/quarto quarto render test.md --to revealjs --log-level warning，现在您的幻灯片将有三张幻灯片（按空格键或箭头键进行导航）。
现在您的幻灯片已准备好部署到远程服务器。将html文件和相关文件夹（在我们这里的用例中，文件 test.html 和文件夹 test_files）复制到FTP服务器，您的网站就可以公开访问了。很好，不是吗？