Quarto:Markdown 又何必只是 Markdown

本贴最后更新于 494 天前,其中的信息可能已经时过境迁

关联文章::设置 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 更新了该帖

相关帖子

欢迎来到这里!

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

注册 关于
请输入回帖内容 ...
  • zhanganchi352242 2 评论

    您好,我有一些关于导出到 Word 时行间公式的问题想请教一下,不知您是否能拨冗回答?

    1. 行间公式是否可以对应到 refrence.docx 中的某个指定段落样式?例如,我校本科毕业论文模板会要求行间公式拥有段前段后 0.5 行的行距,因而需要在正文之外新设一个行间公式样式。鄙人检查了 Quarto 关于 Word 导出的相关文档,以及 pandoc 默认的模板,均未找到对应于行间公式的样式。现在导出的行间公式虽有居中,但样式检查器显示其仍为正文样式
    2. 行间公式的交叉引用如何在书写思源时创建?我在 Quarto 文档中发现创建公式的交叉引用需要在标明公式结束的 $$ 后立刻添加 {#公式名},感觉没办法在写思源的时候就创建好
    1 操作
    zhanganchi352242 在 2022-12-07 13:14:27 更新了该回帖
    第一个问题我没法回答,目前用公式不多,不了解。第二个问题首先,思源不是传统的 markdown 笔记,只适合写初稿,如果要搭配 quarto,我还是习惯用 vscode 写 md
    Achuan-2 1
    @Achuan-2 好的好的,非常感谢您的回复,我今天折腾了一天也没找到简单的公式按章自动编号与交叉引用资料,英文水平也不太够,阅读软件的英文文档也有些费劲,看来想在思源内就完成论文终稿的写作不太现实,能在初稿前享受内容与排版分离已经很好了。感谢您的分享,没有你这篇文章我完全不知道如何开始尝试 md 转 word :-)
    zhanganchi352242
  • 其他回帖
  • 👍 👍

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

    1 回复
  • 奈斯,有点想上手玩玩了。

  • 查看全部回帖