~bzg/orgweb

ref: 56b3377a980d39271de8c6a89060ca776968213a orgweb/quickstart.org -rw-r--r-- 8.8 KiB
56b3377aBastien .build.yml and publish.sh: Load org-contrib/ox-extra and use it 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
#+TITLE: Quickstart | Org mode
#+setupfile: setup.org
#+description: Org: an Emacs Mode for Notes, Planning and Authoring
#+include: "./resources/preamble.html" export html

* Getting started with Org-mode
  :PROPERTIES:
  :CUSTOM_ID: getting-started
  :END:

In its simplest form, Org is like any other markup language.

You can write [[https://orgmode.org/worg/dev/org-syntax.html][Org syntax]] in any text editor.

However, to experience the full potential of Org you need an editor
that transforms Org syntax into a living, interactive document.

#+begin_center
#+attr_html: :class btn
*[[https://orgmode.org/org.html#Installation][Install Org]]*
#+end_center

* Preamble
  :PROPERTIES:
  :CUSTOM_ID: preamble
  :END:

At the start of a file (before the first heading), it is common to
set the title, author and other [[https://orgmode.org/manual/Export-Settings.html][export options]].

#+BEGIN_SRC org
,#+title: The glories of Org
,#+author: A. Org Writer
#+END_SRC

* Heading
  :PROPERTIES:
  :CUSTOM_ID: headings
  :END:

Lines that start with an asterisk ~*~ are [[https://orgmode.org/worg/dev/org-syntax.html#Headlines_and_Sections][headings]].

A single ~*~ denotes a 1st-level heading, ~**~ denotes a 2nd-level
heading, etc.

#+BEGIN_SRC org
,* Welcome to Org-mode
,** Sub-heading
Each extra ~*~ increases the depth by one level.
#+END_SRC

In their simplest form headings are just the start of a section.
However, any heading can also become a [[https://orgmode.org/manual/TODO-Items.html][TODO item]].

TODO items are the basic building block that Org uses to track and
organize all kinds of tasks.

To add a TODO item to a heading, start the heading with a TODO
keyword such as ~TODO~ or ~HOLD~.

#+BEGIN_SRC org
,* TODO Promulgate Org to the world
,** TODO Create a quickstart guide
#+END_SRC

* Markup
  :PROPERTIES:
  :CUSTOM_ID: markup
  :END:

To mark up text in Org, simply surround it with one or more marker
characters.  *Bold*, /italic/ and _underline_ are fairly intuitive, and the
ability to use +strikethrough+ is a plus.  You can _/*combine*/_ the basic
markup in any order, however ~code~ and =verbatim= need to be the
*_~inner-most~_* markers if they are present since their contents are
interpreted =_literally_=.

#+begin_example
To markup text in Org, simply surround it with one or more marker characters.
*Bold*, /italic/ and _underline_ are fairly intuitive, and the ability to use
+strikethrough+ is a plus.  You can _/*combine*/_ the basic markup in any
order, however ~code~ and =verbatim= need to be the *_~inner-most~_* markers
if they are present since their contents are interpreted =_literally_=.
#+end_example

See [[https://orgmode.org/worg/dev/org-syntax.html#Emphasis_Markers][Emphasis Markers]] for more details.

* Lists
  :PROPERTIES:
  :CUSTOM_ID: lists
  :END:

Unordered lists start with ~+~, ~-~, or ~*~[fn::~*~ cannot be used to start
a plain list if it is immediately preceded by a newline because it
will be interpreted as a heading.].  Ordered lists start with ~1.~, ~1)~,
~A.~, or ~A)~.  Ordered and unordered bullets can be nested in any order.

#+BEGIN_SRC org
To buy:
1. Milk
2. Eggs
   - Organic
3. Cheese
   + Parmesan
   + Mozzarella
#+END_SRC

Lists can contain checkboxes ~[ ]~, ~[-]~, ~[X]~.
#+BEGIN_SRC org
- [ ] not started
- [-] in progress
- [X] complete
#+END_SRC

Lists can contain tags (and checkboxes at the same time).
#+BEGIN_SRC org
- [ ] fruits :: get apples
- [X] veggies :: get carrots
#+END_SRC

* Links
  :PROPERTIES:
  :CUSTOM_ID: links
  :END:

To create a link put the target between two square brackets, like so: ~[[target]]~.
You can include a description in square brackets after the target ~[[target][desc]]~.

The order is easy to remember because it is the same as an html =<a>=
tag ~<a href="target">desc</a>~ and you can't mix up brackets and
parentheses because there are only square brackets!

Org supports a wide variety of types of link targets, and you can also
[[https://orgmode.org/manual/Adding-Hyperlink-Types.html][add your own]].
Link types are indicated with a ~type:~ prefix, i.e., ~[type:target]~.
If no ~type:~ is provided, org searches the current file for a heading
that matches ~target~.

Some examples:
#+BEGIN_EXAMPLE
[[https://orgmode.org][a nice website]]
[[file:~/Pictures/dank-meme.png]]
[[earlier heading][an earlier heading in the document]]
#+END_EXAMPLE

** More info
For more on links, see the manual sections for
[[https://orgmode.org/manual/Internal-Links.html][Internal Links]] and
[[https://orgmode.org/manual/External-Links.html][External Links]].

* Images
  :PROPERTIES:
  :CUSTOM_ID: images
  :END:

Org mode automatically recognizes and renders image links during
export.  Just link to an image (don't include a description). That's
it. \\
~[[https://upload.wikimedia.org/wikipedia/commons/5/5d/Konigsberg_bridges.png]]~

#+attr_html: :height 120px
[[https://upload.wikimedia.org/wikipedia/commons/5/5d/Konigsberg_bridges.png]]

Images located on your computer can also be rendered in the Emacs
buffer with =C-c C-x C-v=.

* Blocks
  :PROPERTIES:
  :CUSTOM_ID: blocks
  :END:

Org mode uses =#+BEGIN= ... =#+END= blocks for many purposes.
Some of the basic blocks types quote, example, and src.

If you all you need is monospace text, you can use an example block.
#+BEGIN_SRC org
,#+begin_example
monospace
,#+end_example
#+END_SRC

However, example blocks do not give you the power of [[https://orgmode.org/worg/org-contrib/babel/][Org babel]].
For that you need a source block.
Source blocks provide syntax highlighting, code execution, literate programming, and more.
#+BEGIN_SRC org
,#+begin_src emacs-lisp
(message "Hello world")
,#+end_src
#+END_SRC

** More info
A hello world example cannot even begin to scratch the surface
Org mode's support for [[https://orgmode.org/manual/Working-with-Source-Code.html][working with source code]].

* Tables
  :PROPERTIES:
  :CUSTOM_ID: tables
  :END:

Org mode comes with a table editor complete with support cell references
and formulas.

In its simplest form a table is text separated using pipes ~|~.

#+BEGIN_SRC org
| I    | am  | a    | table |
| with | two | rows | !     |
#+END_SRC

A more useful example is this comparison of existing Literate
programming / reproducible research tools (from [[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

Worried about aligning free text tables?
Org mode does it in a single keystroke -- =tab=.

* Comments
  :PROPERTIES:
  :CUSTOM_ID: comments
  :END:

Org mode has a variety of ways to add comments.

- Line comments start with ~#~.
- Inline comments wrap ~@@comment:like so@@~.
- Block comments are wrapped with ~#+BEGIN_COMMENT~ and ~#+END_COMMENT~.
- Section comments can be created by adding the ~COMMENT~ keyword to a heading ~*
  COMMENT like so~[fn::There are a number of more granular ways to control the
  exact behavior of headings, including use of the special tags ~:ARCHIVE:~ and
  ~:noexport:~.].

#+BEGIN_SRC org
# A line comment

Example of an @@comment:inline@@ comment.

Inline comments are used for end of line comments. @@comment:~#~ won't
work@@ Since # only only works if preceeded by a newline follow by
whitespace.

,#+begin_comment
This is a block comment.
It can span multiple line.
As well as other markup.
,#+begin_src emacs-lisp
(+ 1 2)
,#+end_src
,#+end_comment

,* A top level heading
,** COMMENT This section and subsections are commented out
,*** This heading inherits the =COMMENT= keyword
This text is commented out
,** This heading is not commented
This text will be exported and code blocks will run.
#+END_SRC

* Macros
  :PROPERTIES:
  :CUSTOM_ID: macros
  :END:

Org has many more advanced features built into its syntax.  To give
only a single example, let's take a look at [[https://orgmode.org/manual/Macro-Replacement.html][macros]].

#+BEGIN_SRC org
,#+macro: attn _*/$1/*_
{{{attn(Attention! This text gets all the markup!)}}}

,#+html_head: <style>.red{color:red;}</style>
,#+latex_header: \usepackage{xcolor}
,#+macro: red @@html:<span class="red">$1</span>@@@@latex:\textcolor{red}{$1}@@
Regular text. {{{red(This text will be red.)}}} More regular text.
#+END_SRC

* Next steps
  :PROPERTIES:
  :CUSTOM_ID: next-steps
  :END:

Looking for something in particular?  The [[file:manual/][manual]] ([[file:org.pdf][PDF]]) is a good place
to start.

Looking for something between this quickstart and the manual?  The
[[file:guide/][guide]] ([[file:orgguide.pdf][PDF]]) is worth a shot.