Quarto:Markdown 又何必只是 Markdown

关联文章::设置 word 模板,Markdown 也能自动转换为美观规范的 Word 文档

主要介绍怎么把思源笔记内的笔记快速导出为正式的文档。

为什么要用 Quarto?

先简单介绍下 Quarto,官网地址 https://quarto.org/

官网是这样介绍的:

Quarto is an open-source scientific and technical publishing system built on Pandoc

  • Create dynamic content with Python, R, Julia, and Observable.
  • Author documents as plain text markdown or Jupyter notebooks.
  • Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.
  • Author with scientific markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more.

简单来说,Quarto 这个软件可以

  • 用来写代码:类似 Jupyter Notebook,可以 Markdown 和代码一起写,并能渲染代码结果到文档里,支持的语言有 Python、R、Julia 和 Observable,能将渲染结果输出为 HTML、PDF、Word 和 GFM Markdown。对于输出为 Markdown,公式还支持直接转换为 WebTex 图片,方便发布到其他博客或放入笔记软件里;

  • 用来写严肃的报告:相当于 pandoc 加强版和 LaTex 简易版,支持导出为 PDF、Word,并且支持交叉引用,可以引用图表、引用文献。

  • 用来写博客、写书。

Quarto 可以说是下一代 RMarkdown,相比 RMarkdown,将环境给大统一,更好的适配 VSCode,你甚至不需要有 R 环境、安装 Rstudio,就能用 Quarto 写文章和报告。我对 Quarto 的整体印象,可以概括为“枢纽”二字,能写代码,能与 Jupyter Notebook 相互转换,能将 Markdown 导出为各种常用格式,可以当成简易版的 LaTex 写报告,将 Markdown 的生态大大强化。

而 Quarto 对于 Markdown 的处理仅仅只是将文件后缀由 md 改为了 qmd,并在 yaml 中输入参数即可。(当然 Quarto 也有独属的 Markdown 书写方言,起强化 Markdown 排版作用)

本文的重点会聚焦于怎么用 Quarto 将 Markdown 输出为 GFM、Word、PDF 文档,侧重于文档写作。至于写代码、写博客、写书部分,限于篇幅,建议去看官方文档

Quarto 环境配置

Quarto - Get Started 页面下载 Quarto Cli 软件,然后选择你喜欢的编辑器搭配环境即可。

image

我这里推荐的是 VSCode。微软有两种软件:一种是 VSCode,一种是其他软件。只要你吹 VSCode,我们就是好朋友。

image

要在 VSCode,只需要安装 vscode-quarto 插件,即可开箱使用。

用 VSCode 有几个好处

  • vscode-quarto 插件可以提供基本的语法提示功能,还有 Github Copilot 来 AI 提示。
  • 文件夹内各种格式随意创建:.ipynb.qmd.md.py.R
  • VSCode 有 LaTeX 插件,可以用 Quarto 导出 ducument.tex,再用网上的模板渲染成自己需要的文档格式。

注 1:

虽然这里只介绍用 VSCode,但 Quarto 本家的 RStudio 对 Quarto 的适配也非常好,代码运行结果可以直接在代码块显示(VSCode 只能输出在终端或者渲染在最终文档里),可以切换为 Visual 模式(类似于 Markdown 笔记软件的即时渲染模式),Visual 模式支持斜杆命令输入各种块。所以还是很强大的。但本人是坚定的 VSCode 拥护者,RStudio 只能是陪衬辅助,不会是主力。

注 2:

VSCode 用 qmd 写 R 代码其实不是很方便,如果要用 VSCode 写 R 代码,我个人是建议用 jupyter 写,然后用 quarto convert xxx.ipynb 转换为 qmd,再进行渲染。嫌麻烦的话还是建议用 RStudio 吧。

如果你需要导出 pdf,又没有 LaTeX 环境,可以用 quarto install 安装 mini 版的 tinytex

quarto install tinytex --update-path

个人用 Quarto 的流程

先在思源笔记内写稿子,导出为 md,将 md 后缀改为 qmd,在开头加上 YMAL 头进行渲染设置,点击 VSCode 右上方的渲染按钮进行渲染,得到文档。

image

qmd 补充语法简单介绍

Quarto 相比于 GFM,还是加了一些自己的排版语法的,具体可以去官方文档的 Authoring 章节查看。

我这里只提几点

图片

图标标注:如果开启了图片编号,默认 alt 文本会作为图片的标注,title 是不会作为标题的(不知道有没有配置选项,目前还找不到)

![alt](src "title")

图片调整大小

![](figure.png){fig.width='50%'}

对于 pdf 输出,众所周知,LaTeX 渲染的 pdf 图片是薛定谔式出现的,可以设置 fig.pos='H' 来固定图片位置

![](figure.png){fig.pos='H'}

设置图片 label,用于交叉引用(注意,只能是 #fig-+label)

![](figure.png){#fig-first}

表格

| fruit  | price  |
|--------|--------|
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |

设置表题 : Fruit prices

| fruit  | price  |
|--------|--------|
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |

: Fruit prices

设置表格每列的宽度

| fruit  | price  |
|--------|--------|
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |

: Fruit prices {tbl-colwidths="[75,25]"}

设置表格 label,用于交叉引用(注意,只能是 #tbl-+label)

| fruit  | price  |
|--------|--------|
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |

: Fruit prices {#tbl-fruit}

图表交叉引用

文字(见 @tbl-fruit)
文字(见 @fig-first)

渲染结果会是:

文字(见表 1)

图片(见图 1)


注意:交叉引用 @ 前需要有一个空格

注意,Quarto 默认是图表题是 Figure 和 Table,如果要改为中文需要在 YAML 里添加配置

crossref:
  chapters: true
  fig-title:  # (default is "Figure")
  tbl-title:  # (default is "Table")
  title-delim: "."  # (default is " "), not for pdf
  fig-prefix:  # (default is "Figure")
  tbl-prefix:  # (default is "Table")

文献引用

需要准备一个 references.bib,里面放入参考文献的 bibtex 或 bibLatex 格式的 metadata。

并在 YAML 里配置

bibliography: references.bib

就可以在文献里同样用 @ 来引用参考文件了。

可以设置引用和末尾生成参考文献格式的样式

对于导出 word,用的是 pandoc 只能设置为 citeproc(最大的问题是中英文参考文献无法区分)

cite-method: citeproc

对于导出 pdf,可以设置更强大的 biblatex


cite-method: biblatex

YAML 模板

前面扯这么多,其实这部分才是本文核心(滑稽)。

毕竟只需要将 YAML 内容粘贴到 qmd 最前面,就可以设置渲染格式了

GFM 模板

官方配置文档:GFM Markdown

---
title: "My Document"
author:
  - "Achuan-2"
date: "2022.11.19"
date-format: "YYYY.MM.DD"
toc: true
shift-heading-level-by: -1
crossref:
  chapters: true
  fig-title:  # (default is "Figure")
  tbl-title:  # (default is "Table")
  title-delim: "."  # (default is " "), not for pdf
  fig-prefix:  # (default is "Figure")
  tbl-prefix:  # (default is "Table")
format: 
  gfm:
      html-math-method: katex # webtex, mathjax, katex
---

强的地方在于生成的 md,是带有交叉引用功能的(通过 html 锚点实现)

Word 模板

官方配置文档:Word

---
title: "My Document"
format:
  docx:
    toc: true
    number-sections: false
    highlight-style: github
    code-line-numbers: true
    link-citations: true  # 设置正文引用可以超链接到参考文献表中相应的条目,默认为 false,当然true啦
    reference-section-title: "参考文献"
    bibliography: references.bib
    reference-doc: "F:\\OneDrive\\文档\\模板\\ref.docx"
    csl: "gb-t-7714-2015-numeric-bilingual-no-uppercase-no-url-doi.csl"
---

导出 Word 部分,其实用的就是 pandoc,但是相比 pandoc 就更方便了,写完直接点击渲染按钮就可以。如何设置 word 模板可以见之前写的:设置 word 模板,Markdown 也能自动转换为美观规范的 Word 文档。里面也分享了我用的 word 文档。

中文 PDF 模板

官方配置文档:PDF

对于 LaTex 真是又爱又恨,看 PDF 的 YAML 设置这么长就知道了,orz。

---
title: "My Document"
author:
  - "Achuan-2"
date: "2022.11.19"
date-format: "YYYY.MM.DD"
toc: true
number-sections: true
shift-heading-level-by: -1
monofont: "Consolas"
crossref:
  chapters: true
  fig-title:  # (default is "Figure")
  tbl-title:  # (default is "Table")
  title-delim: "-"  # (default is ":"), not for pdf
  fig-prefix:  # (default is "Figure")
  tbl-prefix:  # (default is "Table")
format: 
  pdf:
    # toc
    toc-depth: 3
    toc-title: Contents
    # cite
    cite-method: biblatex # biblatex,citeproc
    bibliography: references.bib
    biblio-title: References
    # output
    documentclass: article # scrartcl,article, report or book
    papersize: a4 # a4, letter
    colorlinks: true
    #classoption: [twocolumn,landscape] 
    keep-tex: true
    fig-pos: 'H'
    tbl-cap-location: top
    fig-cap-location: bottom
    listings: false
    code-block-bg: '#f6f8fa'
    highlight-style: github
    code-block-border-left: false
    geometry:
      - top=30mm
      - left=20mm
      - heightrounded
    include-in-header:
      text: |
        \usepackage{ctex}    % CJK 包
        \usepackage[backend=biber,style=gb7714-2015,gbnamefmt=lowercase]{biblatex}
        \usepackage[dvipsnames]{xcolor}
        \setCJKmainfont[AutoFakeBold = {2.25}]{宋体}
        \setmainfont{Times New Roman} %英文字體調整
        \usepackage{caption}
        \captionsetup[figure]{labelformat=simple, labelsep=period}
        \captionsetup[table]{labelformat=simple, labelsep=period}        

---

注意

  • 对于输出 PDF 来说,比如 <region> 这种格式不能直接输出显示,需要改成 \<region\>

  • 思源导出图片会加两边加零宽字符,导致 alt 无法转化为图片标题。需要用 sublime text 等软件去掉。

    image


暂时就到这里结束了,摸鱼了 1h 半写这篇文章 😁。

4 操作
Achuan-2 在 2022-11-20 06:29:33 更新了该帖
Achuan-2 在 2022-11-19 17:15:45 更新了该帖
Achuan-2 在 2022-11-19 17:12:59 更新了该帖
Achuan-2 在 2022-11-19 17:12:40 更新了该帖

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • founder
    订阅者

    👍 👍

  • DataWealth
    订阅者

    我就说谁,原来是风老哥,问题是没有好的 variable window 就很不方便啊

    1 回复
  • Achuan-2
    订阅者 作者

    我主要就是拿来写报告的哈哈哈