org-mode
1. Markup
1.1. Tables
1.1.1. Table.el Format
Please note that a Chinese character is considered to occupy two spaces, while one space in the plain format.
2. “TODO” Functionality
2.1. Creating TODO items
Only headlines can become TODO items. By adding the word TODO
to the beginning
of the headline, it becomes a TODO item. E.g.,
*** TODO Write letter to Sam Fortune
In contrast, by adding the word DONE
to the beginning, the headline becomes a
DONE item.
C-c C-t
(M-x org-todo
): Rotate the TODO state cycle, TODO -> DONE ->
(unmarked).
2.2. Logging State Changes
C-u C-c C-t
(org-mode
with a C-u
prefix): When called at an unmarked or
TODO headline, change it to the next state, prompt a interactive buffer for
a note of this change, and record the time. The note and time is inserted as a
list below the head line.
Automatic logging: See
- Closing items: automatically log time, etc.
2.3. Checkboxes
Plain lists item can be made into a checkbox by starting it with the string [
]
. Done checkbox starts with [X]
. Note that X
is in capital
letter. Intermediate checkbox starts with [-]
.
C-c C-c
(org-toggle-checkbox
): Rotate the cycle [ ] -> [X] (Note no unmarked
status).
- With a single prefix argument, change unmarked item to [ ], or marked item to unmarked one.
- With two single prefix arguments, set it to intermediate state.
2.4. Subtasks
By adding [/]
or [%]
anywhere in the parent headline, it can capture the
fraction or percentage of DONE items in the children headlines. The parent
headline itself can be a TODO/DONE item or an unmarked item. The statistics is
updated each time the TODO status of a child is changed through C-c C-t
, or
when pressing C-c C-c
at the parent headline.
This can be applied to checkboxes too. By adding [/]
or [%]
anywhere in
the text, it can track the checkboxes in the lists below that position.
3. Hyperlinks
3.1. Internal links
3.1.1. Links to Entries
- By custom id: If the
CUSTOM_ID
property of the entry is set to “my-custom-id”, then[[#my-custom-id]]
points to that entry. - By entry name: If the entry is named “Some section”, then
[[*Some section]]
points to that entry.
3.1.2. Links to Dedicated Targets
If <<My Target>>
is put some point in the text, then [[My Target]]
points to the point.
3.1.3. Links to Blocks, Tables, Lists, and Similar Elements
If #+NAME:
keyword for a block / table / list and etc is set to “My Name”, then [[My Name]]
points to the element.
4. LaTeX Export
Metadata:
- Title:
#+TITLE:
- Author:
#+AUTHOR:
Preamble:
- Class: By default, the back-end uses the
article
class.- To change the default class globally, configure
org-latex-default-class
. - To change it locally, add option line
#+LATEX_CLASS:
.
- To change the default class globally, configure
4.1. Compiler Options
To use xelatex: Add
#+LATEX_COMPILER: xelatex
or set it through org-latex-compiler
.
4.2. Previewing LaTeX fragments (esp. math)
Reference:
The preview is based on the LaTeX configuration specified by the variables
org-format-latex-options
: Appearance and math delimiters.org-format-latex-header
: LaTeX preamble used. Packages used (a placeholder in this variable) are specified byorg-latex-default-packages-alist
andorg-latex-packages-alist
(these two define packages used in every file).- Editting these
packages-alist
allows you to introduce packages, but to use macros you still need to modifyorg-format-latex-header
. - Alternatively, you could create your own sty file (in which both packages and
macros are specified) and put them in
the registered directory
(for
MacTeX,
general
answer). My practice is to put my sty file under
~/Library/texmf/tex/latex
.
- Editting these
C-c C-x C-l
(org-latex-preview
) to preview the fragment at point. If there
is no fragment at point, process all fragments in the current entry—between two
headlines.
The preview process to convert LaTeX fragments to image files is defined by
org-preview-latex-default-process
(dvipng
by default). The preview images are located at
org-preview-latex-image-directory
.
Suggestions on markup language conversion:
- org-mode to LaTeX:
- The org-mode export back-end:
- Good: Tidy and elegant LaTeX code, by default using very basic packages only.
- Bad: The labels are by default random indices. (can be adjusted by
org-latex-prefer-user-labels
).
- Pandoc: Requires extra
packages. E.g.,
longtable
for tables,\tightlist
initemize
. - The org-mode back-end is in general better (more specialized and native).
- The org-mode export back-end:
- between lightweight languages like org-mode and markdown, or from heavyweight languages to lightweight ones: Pandoc does a great job. E.g., from markdown to org-mode, the custom ids of headlines will be automatically generated from the headline words.
- With this in mind, a better way to convert markdown to LaTeX might be (1) markdown to org-mode using pandoc, and (2) org-mode to LaTeX using org-mode.
5. HTML Export
5.1. Math
Org options:
org-html-with-latex
controls the exporter used to process LaTeX fragments. By default, it uses MathJax, whose rendering effect cannot compete with LaTeX generated images. Otherwise, it can use any symbol defined in the following variable:org-preview-latex-process-alist
:the
:image-size-adjust
attribute controls image size. The docstring reads “users should use variableorg-format-latex-options
instead.” Adjust thehtml-scale
property in that variable. E.g.,(setq org-format-latex-options (plist-put org-format-latex-options ':html-scale 0.8))
- the
:latex-header
controls the header used to generate images. Leave it as nil, so that the fallback value is used instead, which is controlled byorg-format-latex-header
,org-latex-default-packages-alist
andorg-latex-packages-alist
. Basically, these are the same configurations for previewing LaTeX. See the LaTeX section.
I experimented and found that using the dvisvgm option for
org-html-with-latex
, i.e.,(setq org-html-with-latex 'dvisvgm)
achieves the best quality, but the rendering speed is much slower than mathjax.
HTML Rendering:
- Vertical alignment of LaTeX-generated SVG with the surrounding text can be a problem: Wikipedia
- Wikipedia’s work-around
6. Publishing
Reference:
- https://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html
- https://orgmode.org/worg/org-site-colophon.html
Functions:
- Can be configured to automatically upload related files to a web server.
- Can combine HTML and PDF conversion so that files are available in both formats on the server.
Miscellaneous:
- The publishing functions leaves generated files (e.g.,
.html
,.tex
,.pdf
) in source directories. - A root-relative URL starts with a
/
character. - Force publish (also re-publish the unchanged files):
stackoverflow
C-u M-x org-publish
. - org-info.js:
By default activated with path set to
https://orgmode.org/org-info.js
. TypeM-x customize-group RET org-export-html
and clickOrg Export HTML INFOJS
for options. - Links between project files:
[[file:relative/path/to/another.org][description]]
.