+Org-mode includes@footnote{@file{org-publish.el} is not yet part of
+emacs, so if you are using @file{org.el} as it comes with Emacs, you
+need to download this file separately. Also make sure org.el is at
+least version 4.27.} a publishing management system
+that allows you to configure automatic HTML conversion of
+@emph{projects} composed of interlinked org files. This system is
+called @emph{org-publish}. You can also configure org-publish to
+automatically upload your exported HTML pages and related attachments,
+such as images and source code files, to a web server. Org-publish turns
+org-mode into a web-site authoring tool.
+
+Org-publish has been contributed to Org-mode by David O'Toole.
+
+@menu
+* Configuration:: Defining projects
+* Sample configuration:: Example projects
+* Triggering publication:: Publication commands
+@end menu
+
+@node Configuration, Sample configuration, Publishing, Publishing
+@section Configuration
+
+Publishing needs significant configuration to specify files, destination
+and many other properties of a project.
+
+@menu
+* Project alist:: The central configuration variable
+* Sources and destinations:: From here to there
+* Selecting files:: What files are part of the project?
+* Publishing action:: Setting the function doing the publishing
+* Publishing options:: Tweaking HTML export
+* Publishing links:: Which links keep working after publishing?
+* Project page index:: Publishing a list of project files
+@end menu
+
+@node Project alist, Sources and destinations, Configuration, Configuration
+@subsection The variable @code{org-publish-project-alist}
+@cindex org-publish-project-alist
+@cindex projects, for publishing
+
+Org-publish is configured almost entirely through setting the value of
+one variable, called @code{org-publish-project-alist}.
+Each element of the list configures one project, and may be in one of
+the two following forms:
+
+@lisp
+("project-name" :property value :property value ...)
+
+@r{or}
+
+("project-name" :components ("project-name" "project-name" ...))
+
+@end lisp
+
+In both cases, projects are configured by specifying property values.
+A project defines the set of files that will 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 components of the
+project, which group together files requiring different publishing
+options. When you publish such a ``meta-project'' all the components
+will also publish.
+
+@node Sources and destinations, Selecting files, Project alist, Configuration
+@subsection Sources and destinations for files
+@cindex directories, for publishing
+
+Most properties are optional, but some should always be set. In
+particular, org-publish needs to know where to look for source files,
+and where to put published files.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:base-directory}
+@tab Directory containing publishing source files
+@item @code{:publishing-directory}
+@tab Directory (possibly remote) where output files will be published.
+@end multitable
+@noindent
+
+@node Selecting files, Publishing action, Sources and destinations, Configuration
+@subsection Selecting files
+@cindex files, selecting for publishing
+
+By default, all files with extension @file{.org} in the base directory
+are considered part of the project. This can be modified by setting the
+properties
+@multitable @columnfractions 0.25 0.75
+@item @code{:base-extension}
+@tab Extension (without the dot!) of source files. This actually is a
+regular expression.
+
+@item @code{:exclude}
+@tab Regular expression to match file names that should not be
+published, even though they have been selected on the basis of their
+extension.
+
+@item @code{:include}
+@tab List of files to be included regardless of @code{:base-extension}
+and @code{:exclude}.
+@end multitable
+
+@node Publishing action, Publishing options, Selecting files, Configuration
+@subsection Publishing Action
+@cindex action, for publishing
+
+Publishing means that a file is copied to the destination directory and
+possibly transformed in the process. The default transformation is to
+export Org-mode files as HTML files, and this is done by the function
+@code{org-publish-org-to-html} which calls the HTML exporter
+(@pxref{HTML export}). Other files like images only need to be copied
+to the publishing destination. For non-Org-mode files, you need to
+specify the publishing function.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:publishing-function}
+@tab Function executing the publication of a file.
+@end multitable
+
+The function must accept two arguments: a property list containing at
+least a @code{:publishing-directory} property, and the name of the file
+to be published. It should take the specified file, make the necessary
+transformation (if any) and place the result into the destination folder.
+You can write your own publishing function, but @code{org-publish}
+provides one for attachments (files that only need to be copied):
+@code{org-publish-attachment}.
+
+@node Publishing options, Publishing links, Publishing action, Configuration
+@subsection Options for the HTML exporter
+@cindex options, for publishing
+
+The property list can be used to set many export options for the HTML
+exporter. In most cases, these properties correspond to user variables
+in Org-mode. The table below lists these properties along with the
+variable they belong to. See the documentation string for the
+respective variable for details.
+
+@multitable @columnfractions 0.3 0.7
+@item @code{:language} @tab @code{org-export-default-language}
+@item @code{:headline-levels} @tab @code{org-export-headline-levels}
+@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
+@item @code{:table-of-contents} @tab @code{org-export-with-toc}
+@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
+@item @code{:emphasize} @tab @code{org-export-with-emphasize}
+@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
+@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
+@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
+@item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
+@item @code{:timestamps} .@tab @code{org-export-with-timestamps}
+@item @code{:tags} .@tab @code{org-export-with-tags}
+@item @code{:tables} @tab @code{org-export-with-tables}
+@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
+@item @code{:style} @tab @code{org-export-html-style}
+@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
+@item @code{:inline-images} @tab @code{org-export-html-inline-images}
+@item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
+@item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
+@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
+@item @code{:preamble} @tab @code{org-export-html-preamble}
+@item @code{:postamble} @tab @code{org-export-html-postamble}
+@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
+@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
+@item @code{:author} @tab @code{user-full-name}
+@item @code{:email} @tab @code{user-mail-address}
+@end multitable
+
+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 (@pxref{Export
+options}), however, override everything.
+
+@node Publishing links, Project page index, Publishing options, Configuration
+@subsection Links between published files
+@cindex links, publishing
+
+To create a link from one Org-mode file to another, you would use
+something like @samp{[[file:foo.org][The foo]]} or simply
+@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link
+becomes a link to @file{foo.html}. In this way, you can interlink the
+pages of your "org web" project and the links will work as expected when
+you publish them to HTML.
+
+You may also link to related files, such as images. Provided you are
+careful with relative pathnames, and provided you have also configured
+org-publish to upload the related files, these links will work
+too. @ref{Complex example} for an example of this usage.
+
+Sometime an Org-mode file to be published may contain links that are
+only valid in your production environment, but not in the publishing
+location. In this case, use the property
+
+@multitable @columnfractions 0.4 0.6
+@item @code{:link-validation-function}
+@tab Function to validate links
+@end multitable
+
+@noindent
+to define a function for checking link validity. This function must
+accept two arguments, the file name and a directory relative to which
+the file name is interpreted in the production environment. If this
+function returns @code{nil}, then the HTML generator will only insert a
+description into the HTML file, but no link. One option for this
+function is @code{org-publish-validate-link} which checks if the given
+file is part of any project in @code{org-publish-project-alist}.
+
+@node Project page index, , Publishing links, Configuration
+@subsection Project page index
+@cindex index, of published pages
+
+The following properties may be used to control publishing of an
+index of files or summary page for a given project.
+
+@multitable @columnfractions 0.25 0.75
+@item @code{:auto-index}
+@tab When non-nil, publish an index during org-publish-current-project or
+org-publish-all.
+
+@item @code{:index-filename}
+@tab Filename for output of index. Defaults to @file{index.org} (which
+becomes @file{index.html}).
+
+@item @code{:index-title}
+@tab Title of index page. Defaults to name of file.
+
+@item @code{:index-function}
+@tab Plugin function to use for generation of index.
+Defaults to @code{org-publish-org-index}, which generates a plain list
+of links to all files in the project.
+@end multitable
+
+@node Sample configuration, Triggering publication, Configuration, Publishing
+@section Sample configuration
+
+Below we provide two example configurations. The first one is a simple
+project publishing only a set of Org-mode files. The second example is
+more complex, with a multi-component project.
+
+@menu
+* Simple example:: One-component publishing
+* Complex example:: A multi-component publishing example
+@end menu
+
+@node Simple example, Complex example, Sample configuration, Sample configuration
+@subsection Example: simple publishing configuration
+
+This example publishes a set of Org-mode files to the @file{public_html}
+directory on the local machine.
+
+@lisp
+(setq org-publish-project-alist
+ '(("org"
+ :base-directory "~/org/"
+ :publishing-directory "~/public_html"
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=stylesheet
+ href=\"../other/mystyle.css\"
+ type=\"text/css\">")))
+@end lisp
+
+@node Complex example, , Simple example, Sample configuration
+@subsection Example: complex publishing configuration
+
+This more complicated example publishes an entire website, including
+org files converted to HTML, image files, emacs lisp source code, and
+stylesheets. 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 @file{~/org} and your
+publishable images in @file{~/images}, you'd link to an image with
+@c
+@example
+file:../images/myimage.png
+@end example
+@c
+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 webserver, and publishing images to it.
+
+@lisp
+(setq org-publish-project-alist
+ '(("orgfiles"
+ :base-directory "~/org/"
+ :base-extension "org"
+ :publishing-directory "/ssh:user@@host:~/html/notebook/"
+ :publishing-function org-publish-org-to-html
+ :exclude "PrivatePage.org" ;; regexp
+ :headline-levels 3
+ :section-numbers nil
+ :table-of-contents nil
+ :style "<link rel=stylesheet
+ href=\"../other/mystyle.css\" type=\"text/css\">"
+ :auto-preamble t
+ :auto-postamble nil)
+
+ ("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"))))
+@end lisp
+
+@node Triggering publication, , Sample configuration, Publishing
+@section Triggering publication
+
+Once org-publish is properly configured, you can publish with the
+following functions: