Publishing is configured almost entirely through setting the value of one variable, called org-publish-project-alist. Each element of the list configures one project, and may be in one of the two following forms:

("project-name" :property value :property value ...)

i.e., a well-formed property list with alternating keys and values, or:

("project-name" :components ("project-name" "project-name" ...))

In both cases, projects are configured by specifying property values. A project defines the set of files that are to be published, as well as the publishing configuration to use when publishing those files. When a project takes the second form listed above, the individual members of the :components property are taken to be sub-projects, which group together files requiring different publishing options. When you publish such a "meta-project", all the components are also published, in the sequence given.

Most properties are optional, but some should always be set. In particular, Org needs to know where to look for source files, and where to put published files.

:base-directory

Directory containing publishing source files.

:publishing-directory

Directory where output files are published. You can directly publish to a webserver using a file name syntax appropriate for the Emacs tramp package. Or you can publish to a local directory and use external tools to upload your website (see Uploading Files).

:preparation-function

Function or list of functions to be called before starting the publishing process, for example, to run make for updating files to be published. Each preparation function is called with a single argument, the project property list.

:completion-function

Function or list of functions called after finishing the publishing process, for example, to change permissions of the resulting files. Each completion function is called with a single argument, the project property list.

By default, all files with extension .org in the base directory are considered part of the project. This can be modified by setting the following properties

:base-extension

Extension—without the dot—of source files. This actually is a regular expression. Set this to the symbol any if you want to get all files in :base-directory, even without extension.

:exclude

Regular expression to match file names that should not be published, even though they have been selected on the basis of their extension.

:include

List of files to be included regardless of :base-extension and :exclude.

:recursive

Non-nil means, check base-directory recursively for files to publish.

Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function org-html-publish-to-html which calls the HTML exporter (see HTML Export). But you can also publish your content as PDF files using org-latex-publish-to-pdf, or as ASCII, Texinfo, etc., using the corresponding functions.

If you want to publish the Org file as an .org file but with archived, commented, and tag-excluded trees removed, use org-org-publish-to-org. This produces file.org and puts it in the publishing directory. If you want a htmlized version of this file, set the parameter :htmlized-source to t. It produces file.org.html in the publishing directory(note: If the publishing directory is the same as the source directory, file.org is exported as file.org.org, so you probably do not want to do this.).

Other files like images only need to be copied to the publishing destination; for this you can use org-publish-attachment. For non-Org files, you always need to specify the publishing function:

:publishing-function

Function executing the publication of a file. This may also be a list of functions, which are all called in turn.

:htmlized-source

Non-nil means, publish htmlized source.

The function must accept three arguments: a property list containing at least a :publishing-directory property, the name of the file to be published, and the path to the publishing directory of the output file. It should take the specified file, make the necessary transformation, if any, and place the result into the destination folder.

The property list can be used to set many export options for the HTML and LaTeX exporters. In most cases, these properties correspond to user variables in Org. The table below lists these properties along with the variable they belong to. See the documentation string for the respective variable for details.

When a property is given a value in org-publish-project-alist, its setting overrides the value of the corresponding user variable, if any, during publishing. Options set within a file (see Export Settings), however, override everything.

To create a link from one Org file to another, you would use something like [[file:foo.org][The foo]] or simply [[file:foo.org]] (see External Links). When published, this link becomes a link to foo.html. You can thus interlink the pages of your "Org web" project and the links will work as expected when you publish them to HTML. If you also publish the Org source file and want to link to it, use an http link instead of a file: link, because file links are converted to link to the corresponding .html file.

Links to encrypted Org files, like [[file:foo.org.gpg]] are also supported.

You may also link to related files, such as images. Provided you are careful with relative file names, and provided you have also configured Org to upload the related files, these links will work too. See Example: complex publishing configuration, for an example of this usage.

Links between published documents can contain some search options (see Search Options in File Links), which will be resolved to the appropriate location in the linked file. For example, once published to HTML, the following links all point to a dedicated anchor in foo.html.

[[file:foo.org::*heading]]
[[file:foo.org::#custom-id]]
[[file:foo.org::target]]

The following properties may be used to control publishing of a map of files for a given project.

:auto-sitemap

When non-nil, publish a sitemap during org-publish-current-project or org-publish-all.

:sitemap-filename

Filename for output of sitemap. Defaults to sitemap.org, which becomes sitemap.html.

:sitemap-title

Title of sitemap page. Defaults to name of file.

:sitemap-style

Can be list (site-map is just an itemized list of the titles of the files involved) or tree (the directory structure of the source files is reflected in the site-map). Defaults to tree.

:sitemap-format-entry

With this option one can tell how a site-map entry is formatted in the site-map. It is a function called with three arguments: the file or directory name relative to base directory of the project, the site-map style and the current project. It is expected to return a string. Default value turns file names into links and use document titles as descriptions. For specific formatting needs, one can use org-publish-find-date, org-publish-find-title and org-publish-find-property, to retrieve additional information about published documents.

:sitemap-function

Plug-in function to use for generation of the sitemap. It is called with two arguments: the title of the site-map and a representation of the files and directories involved in the project as a nested list, which can further be transformed using org-list-to-generic, org-list-to-subtree and alike. Default value generates a plain list of links to all files in the project.

:sitemap-sort-folders

Where folders should appear in the sitemap. Set this to first (default) or last to display folders first or last, respectively. When set to ignore, folders are ignored altogether. Any other value mixes files and folders. This variable has no effect when site-map style is tree.

:sitemap-sort-files

How the files are sorted in the site map. Set this to alphabetically (default), chronologically or anti-chronologically. chronologically sorts the files with older date first while anti-chronologically sorts the files with newer date first. alphabetically sorts the files alphabetically. The date of a file is retrieved with org-publish-find-date.

:sitemap-ignore-case

Should sorting be case-sensitive? Default nil.

Org mode can generate an index across the files of a publishing project.

:makeindex

When non-nil, generate in index in the file theindex.org and publish it as theindex.html.

The file is created when first publishing a project with the :makeindex set. The file only contains a statement #+INCLUDE: "theindex.inc". You can then build around this include statement by adding a title, style information, etc.

Index entries are specified with INDEX keyword. An entry that contains an exclamation mark creates a sub item.

*** Curriculum Vitae
#+INDEX: CV
#+INDEX: Application!CV

This example publishes a set of Org files to the public_html directory on the local machine.

(setq org-publish-project-alist
      '(("org"
         :base-directory "~/org/"
         :publishing-function org-html-publish-to-html
         :publishing-directory "~/public_html"
         :section-numbers nil
         :with-toc nil
         :html-head "<link rel=\"stylesheet\"
                    href=\"../other/mystyle.css\"
                    type=\"text/css\"/>")))

This more complicated example publishes an entire website, including Org files converted to HTML, image files, Emacs Lisp source code, and style sheets. The publishing directory is remote and private files are excluded.

To ensure that links are preserved, care should be taken to replicate your directory structure on the web server, and to use relative file paths. For example, if your Org files are kept in ~/org/ and your publishable images in ~/images/, you would link to an image with

file:../images/myimage.png

On the web server, the relative path to the image should be the same. You can accomplish this by setting up an images/ folder in the right place on the web server, and publishing images to it.

(setq org-publish-project-alist
      `(("orgfiles"
         :base-directory "~/org/"
         :base-extension "org"
         :publishing-directory "/ssh:user@host:~/html/notebook/"
         :publishing-function org-html-publish-to-html
         :exclude ,(rx (or "PrivateFile.org" (seq line-start "private/"))) ;; regexp
         :headline-levels 3
         :section-numbers nil
         :with-toc nil
         :html-head "<link rel=\"stylesheet\"
                  href=\"../other/mystyle.css\" type=\"text/css\"/>"
         :html-preamble t)

        ("images"
         :base-directory "~/images/"
         :base-extension "jpg\\|gif\\|png"
         :publishing-directory "/ssh:user@host:~/html/images/"
         :publishing-function org-publish-attachment)

        ("other"
         :base-directory "~/other/"
         :base-extension "css\\|el"
         :publishing-directory "/ssh:user@host:~/html/other/"
         :publishing-function org-publish-attachment)
        ("website" :components ("orgfiles" "images" "other"))))