Doc-org generates pdf files by combining org-mode and latex.

Org mode is a markup language like markdown, but more powerful. Since it is very concise and readable, it is used to describe the body of your document. Emacs is used to export org mode to latex.

Latex is the best way to create awesome pdf files. It is used to describe how your document should look like.

Doc-org runs on docker, which means you don’t need to have latex or emacs installed on your machine and you can use it to generate documents with Continuous Integration.

Docker is a prerequisite. See official installation instructions.

In order to download doc-org run this command:

git clone https://github.com/doc-org/doc-org

In this directory there is the doc-org script, which is used to generate documents.

Inside the doc-org directory run:

git pull --rebase

Run doc-org -h to get help and doc-org -v to get the software version.

$ ./doc-org -h
doc-org 0.1.0
Generate pdf by combining org-mode and latex.
USAGE:
    doc-org [document-dir]
FLAGS:
    -h       Prints help information
    -v       Prints version
ARGS:
    [document-dir]

You can specify the directory of your document as the first argument. Otherwise, if you run doc-org without arguments it will use the current directory,

The directory should contain these files:

main.org

The first org file that will be compiled. In this file you can include other org or latex files.

header.tex

The latex header, that contains document class, packages and so on (required if auto_latex: false).

config.json

Contains configuration parameters (optional).

init.el

Custom emacs configuration. Emacs sources this file before converting org to latex (optional).

config.json file and all of its fields are optional. This is an example of this file, where all parameters are present:

{
    "pdf_filename": "my document",
    "auto_latex": false,
    "shell_escape": false
}

pdf_filename

Name of the output pdf file without extension.

auto_latex

If true org-mode creates the necessary latex code automatically. header.tex file is not used and doc-org does not modify the output of emacs. False by default.

shell_escape

Enable latex to run external commands. Useful when working with graphviz for example. False by default.

See examples git repository. Github actions are used to automatically export to latex and pdf after each push to the repository.

Doc-org uses emacs to convert the main.org org-mode file to the main.tex latex file. You can customize emacs export function with the init.el file. Then, latexmk is used to convert main.tex and header.tex to the final pdf.

+----------+   +---------+
| main.org |   | init.el |
+-----+----+   +----+----+
      |             |
      |             |
      +------+------+
             |
             v
           emacs
             |
             v
       +-----+----+     +------------+
       | main.tex |     | header.tex |
       +-----+----+     +-----+------+
             |                |
             |                |
             +-------+--------+
                     |
                     v
                  latexmk
                     |
                     v
                  +--+--+
                  | pdf |
                  +-----+

The main.tex file will look like this:

\input{header.tex}
\begin{document}
% contents of main.org translated into latex
\end{document}

Doc-org is mainly for people who already have a latex template and want to use org-mode to write the body of their document. Anyway, if you are already happy with the default latex export function of org mode (i.e. you don’t want header.tex to be included automatically), you can set auto_latex: true in your config.json file.

With doc-org you have full control of the latex output, because Org mode supports embedded latex code, therefore you can use latex inside an org file when needed. Furthermore, emacs supports tons of different customization options, which can be set with the init.el file.

• tables
• images
• lists
• code
• horizontal