#+TITLE: 快速开始 | Org 主模式
#+setupfile: setup.org
#+include: "resources/preamble.html" export html

* 开始使用 Org@@comment:Get Started@@
  :PROPERTIES:
  :CUSTOM_ID: getting-started
  :END:

简单来说，Org 与任何其它的标记语言一样：你可以在任何文本编辑器里使用 [[file:../worg/dev/org-syntax.html][Org 语法]] 编辑文档。

然而，为了体验 Org 全部的潜力，你需要一个能够把 Org 语法转换为一个可互动文档的编辑器。

#+begin_center
#+attr_html: :class btn
*[[file:../org.html#Installation][安装 Org]]*
#+end_center

* 文档引言@@comment:Preamble@@
  :PROPERTIES:
  :CUSTOM_ID: preamble
  :END:

在文件的最开始（第一个章节标题之前），你常常需要设置标题、作者以及其它[[file:../manual/Export-Settings.html][导出选项]]。

#+BEGIN_SRC org
,#+title: Org 的荣光
,#+author: Org 用户
#+END_SRC

* 章节标题@@comment:Heading@@
  :PROPERTIES:
  :CUSTOM_ID: headings
  :END:

由星号 ~*~ 开始的行被称作[[file:../worg/dev/org-syntax.html#Headlines_and_Sections][章节标题（heading）]]。

一个星号 ~*~ 代表一级章节标题，两个星号 ~**~ 代表二级章节标题，等等。

#+BEGIN_SRC org
  ,* 欢迎来到 Org
  ,** 子章节标题
  每个额外的 ~*~ 为章节的深度增加一级。
#+END_SRC

简单来说，章节标题代表了一个章节的开始。然而，任何章节也可以成为一个[[file:../manual/TODO-Items.html][待办事项]]。

待办事项是 Org 用来跟踪、整理各类的任务的基本模块。

若要把一个现有的章节标题转换为一个待办事项，仅需在其开头加上一个待办关键词，例如 ~TODO~ 或者 ~HOLD~​。

#+BEGIN_SRC org
  ,* TODO 向世界介绍 Org
  ,** TODO 创建一个快速开始指南
#+END_SRC

* 标记@@comment:markup@@
  :PROPERTIES:
  :CUSTOM_ID: markup
  :END:

# 代码 = code; 逐字 = verbatim
若要在 Org 里标记文字，仅需要在其两侧使用标记字符。​*加粗*​、​/斜体/​、​_下划线_​都很简单；你甚至能够轻松地使用​+删除线+​。你可以任意组合这些基本的标记，但需要记住一点，若使用了​~代码~​或​=逐字=​这两个标记之一，它们需要在这个组合的​*_~最里侧~_*​，因为它们包含的内容是​=按字面=​解析的。

#+begin_example
若要在 Org 里标记文字，仅需要在其两侧使用标记字符。​*加粗*​、​/斜体/​、​_下划线_​都很简单；你甚至能够轻松地使用​+删除线+​。你可以任意组合这些基本的标记，但需要记住一点，若使用了​~代码~​或​=逐字=​这两个标记之一，它们需要在这个组合的​*_~最里侧~_*​，因为它们包含的内容是​=按字面=​解析的。
#+end_example

可在[[file:../worg/dev/org-syntax.html#Emphasis_Markers][标记符号（英语）]]里查看更多信息。

** 中文用户
中文用户_​：由于 Org 的限制，标记字符的内侧必须不是空格，而外侧必须是空格（包含换行等）。因此，中文用户需要在使用标记时，可以在有需要时使用零宽空格（16进制代码​~#x200b~​，名称为​~ZERO WIDTH SPACE~​）。使用方法：

（原生 Emacs）快捷键：
#+begin_example
C-x 8 RET 200b RET
#+end_example

使用 Emacs Lisp：
#+begin_src emacs-lisp
(insert-char #x200b)
#+end_src

* 列表@@comment:Lists@@
  :PROPERTIES:
  :CUSTOM_ID: lists
  :END:

# 无序列表 = unordered list; 有序列表 = ordered list
无序列表由​~+~​、​~-~​、​~*~​开头​[fn::~*~​不能被用作一行的最开头，因为这样它会被解析成一个章节标题。]。有序列表由​~1.~​、​~1)~​、​~A.~​、​~A)~​开头。有序与无序符号可以以任意顺序嵌套。

#+BEGIN_SRC org
  采购单：
  1. 牛奶
  2. 鸡蛋
     - 有机
  3. 调料
     + 糖
     + 盐
#+END_SRC

# 勾选项 = checkbox
列表可包含勾选项​~[ ]~​、​~[-]~​、​~[X]~​。
#+BEGIN_SRC org
  - [ ] 未开始
  - [-] 进行中
  - [X] 已完成
#+END_SRC

# 标签 = tag
列表也可同时包含标签。
#+BEGIN_SRC org
  - [ ] 水果 :: 买苹果
  - [X] 蔬菜 :: 买胡萝卜
#+END_SRC

* 链接
  :PROPERTIES:
  :CUSTOM_ID: links
  :END:

创建链接时把目标放在两对​*半角*​方括号中，例如：​~[[目标]]~​。你也可以在链接里、目标之后添加描述：​~[[目标][描述]]~​。

这个顺序相当好记，因为这跟 HTML 的 =<a>= 标记 ~<a href="目标">描述</a>~ 一样，并且你不可能混淆不同种类的括号，因为 Org 语法里只用中括号。

Org 支持一系列不同的链接目标类型，并且你还可以[[file:../manual/Adding-Hyperlink-Types.html][添加你自己的目标类型]]。链接目标类型由其前缀​~类型:~​表示，例如：​~[[类型:目标]]~​。若没有提供类型，Org 会在当前文件里搜索一个符合​~目标~​的章节标题。

举个例子：
#+BEGIN_EXAMPLE
[[https://orgmode.org][一个网页]]
[[file:~/Pictures/dank-meme.png]]
[[之前的章节标题][此文档里一个之前的章节标题]]
#+END_EXAMPLE

** 更多信息
更多关于链接的信息参见手册（英语）：[[file:../manual/Internal-Links.html][内部链接]]、[[file:../manual/External-Links.html][外部链接]]。

* 图像
  :PROPERTIES:
  :CUSTOM_ID: images
  :END:

Org 会在导出时自动识别且显示图片链接。你只需要链接一个图片，且不提供描述既可。\\
~[[https://orgmode.org/resources/img/quickstart.svg]]~

#+attr_html: :height 120px
[[file:../resources/img/quickstart.svg]]

在你电脑里的图片也可以按 =C-c C-x C-v= 在 Emacs 缓存区里显示。

* 区块
  :PROPERTIES:
  :CUSTOM_ID: blocks
  :END:

Org 主模式里可以包含区块 =#+BEGIN= …… =#+END=​，不同的区块对应不同的用途。基本的区块包括：引用（quote），举例（example），以及源码（src）。

若你只需要等宽文字，你可以使用举例区块。
#+BEGIN_SRC org
,#+begin_example
monospace 等宽
,#+end_example
#+END_SRC

然而，你不能在举例区块里使用 [[file:../worg/org-contrib/babel/][Org Babel]] ----- 你需要使用源码区块。源码区块提供了语法高亮、代码运行、文学编程等等。
#+BEGIN_SRC org
,#+begin_src emacs-lisp
(message "Hello world")
,#+end_src
#+END_SRC

** 更多信息
一个”你好世界“的例子根本不足以向你展示 Org 与源代码的[[file:../manual/Working-with-Source-Code.html][所有功能]]。

* 表格
  :PROPERTIES:
  :CUSTOM_ID: tables
  :END:

Org 主模式内置了一个表格编辑器，并且支持各种与元素引用以及公式的功能。

最简单的表格仅仅是由 ~|~ 分隔开的文本。
#+BEGIN_SRC org
| 我 | 是 | 一个 | 表格 |
| 我 | 有 | 两行 | ！   |
#+END_SRC

这是在一篇论文（[[doi:10.18637/jss.v046.i03][Schulte /et al./ 2012]]）里的一个表格，对比了现有的文学编程与可重复研究工具。

#+BEGIN_SRC org
| Tool         | Literate programming? | Reproducible Research? | Languages |
|--------------+-----------------------+------------------------+-----------|
| Javadoc      | partial               | no                     | Java      |
| Haskell .lhs | partial               | no                     | Haskell   |
| noweb        | yes                   | no                     | any       |
| Sweave       | partial               | yes                    | R         |
| Org-mode     | yes                   | yes                    | any       |
#+END_SRC

担心无法在文本表格中对齐？你只需按一个键 ----- =tab=​。

* 注释
  :PROPERTIES:
  :CUSTOM_ID: comments
  :END:

在 Org 里有很多种方法添加注释：

- 行注释：用​~#~​开头。
- 行内注释：把注释包起来（​~@@comment:就像这样@@~​）。
- 区块注释：用​~#+BEGIN_COMMENT~​和​~#+END_COMMENT~​把注释包起来。
- 章节注释：在章节标题前加上 ~COMMENT~ 可以把这整个章节变成注释[fn::还有一些对章节的更精细的操作，包括使用特殊章节标签​~:ARCHIVE:~​以及​~:noexport:~​。]。

#+BEGIN_SRC org
# 一个行注释

这是一个​@@comment:行内@@​注释。

行内注释可同时被用作行末注释。​@@comment:~#~没有用@@
这是因为​~#~​只在作为一行第一个非空格字符时才是行注释。

,#+begin_comment
这是一个区块注释。
它可以跨越多行，或者其它标记与区块定义。
,#+begin_src emacs-lisp
(+ 1 2)
,#+end_src
,#+end_comment

,* 一个顶层章节标题
,** COMMENT 这个章节与其子章节是注释
,*** 这个章节继承了关键词​=COMMENT=
这段文字是注释
,** 这个章节不是注释
这段文字会被导出，且代码区块会被运行。
#+END_SRC

** 中文用户
_中文用户_​：​=@@comment:行内注释@@=​两侧需要使用零宽空格，详见[[*标记][此章节]]。

* 宏
  :PROPERTIES:
  :CUSTOM_ID: macros
  :END:

  Org 的语法拥有更多高级功能，[[file:../manual/Macro-Replacement.html][这里]]有一个简单的例子。

#+BEGIN_SRC org
,#+macro: attn _*/$1/*_
{{{attn(注意！这个文本有所有标记！)}}}

,#+html_head: <style>.red{color:red;}</style>
,#+latex_header: \usepackage{xcolor}
,#+macro: red @@html:<span class="red">$1</span>@@@@latex:\textcolor{red}{$1}@@
普通文本。{{{red(红色文本。)}}}更多普通文本。
#+END_SRC

* 下一步
  :PROPERTIES:
  :CUSTOM_ID: next-steps
  :END:

在寻找某一个话题？试着读读[[file:../manual/][手册（英语）]]（[[file:../org.pdf][PDF]]）吧。

在寻找这个快速开始与手册之间的内容？试试[[file:../guide/][指导（英语）]]（[[file:../orgguide.pdf][PDF]]）吧。