org-publish.el

   1 ;;; org-publish.el --- publish related org-mode files as a website
   2
   3 ;; Copyright (C) 2006  Free Software Foundation, Inc.
   4
   5 ;; Author: David O'Toole <dto@gnu.org>
   6 ;; Keywords: hypermedia, outlines
   7 ;; Version:
   8
   9 ;; $Id: org-publish.el,v 1.69 2006/06/03 17:17:53 dto Exp dto $
  10
  11 ;; This file is free software; you can redistribute it and/or modify
  12 ;; it under the terms of the GNU General Public License as published by
  13 ;; the Free Software Foundation; either version 2, or (at your option)
  14 ;; any later version.
  15
  16 ;; This file is distributed in the hope that it will be useful,
  17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19 ;; GNU General Public License for more details.
  20
  21 ;; You should have received a copy of the GNU General Public License
  22 ;; along with GNU Emacs; see the file COPYING.  If not, write to
  23 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  24 ;; Boston, MA 02110-1301, USA.
  25
  26 ;;; Commentary:
  27
  28 ;; Requires at least version 4.27 of org.el
  29 ;;
  30 ;; The official org-mode website:
  31 ;; http://staff.science.uva.nl/~dominik/Tools/org/
  32 ;;
  33 ;; Home page for org-publish.el:
  34 ;; http://dto.freeshell.org/notebook/OrgMode.html
  35
  36 ;; This program extends the HTML publishing support of Emacs Org-mode
  37 ;; to allow configurable publishing of related sets of files as a
  38 ;; complete website.
  39 ;;
  40 ;; org-publish.el can do the following:
  41 ;;
  42 ;; + Publish all one's org-files to html
  43 ;; + Upload html, images, attachments and other files to a web server
  44 ;; + Exclude selected private pages from publishing
  45 ;; + Publish a clickable index of pages
  46 ;; + Manage local timestamps, for publishing only changed files
  47 ;; + Accept plugin functions to extend range of publishable content
  48 ;;
  49 ;; Special thanks to the org-mode maintainer Carsten Dominik for his
  50 ;; ideas, enthusiasm, and cooperation.
  51
  52 ;;; Installation:
  53
  54 ;; Put org-publish.el in your load path, byte-compile it, and then add
  55 ;; the following lines to your emacs initialization file:
  56
  57 ;; (autoload 'org-publish "org-publish" nil t)
  58 ;; (autoload 'org-publish "org-publish-all" nil t)
  59 ;; (autoload 'org-publish "org-publish-current-file" nil t)
  60 ;; (autoload 'org-publish "org-publish-current-project" nil t)
  61
  62 ;; NOTE: When org-publish.el is included with org.el, those forms are
  63 ;; already in the file org-install.el, and hence don't need to be put
  64 ;; in your emacs initialization file in this case.
  65
  66 ;;; Usage:
  67 ;;
  68 ;; The program's main configuration variable is
  69 ;; `org-publish-project-alist'. See below for example configurations
  70 ;; with commentary.
  71
  72 ;; The main interactive functions are:
  73 ;;
  74 ;; M-x org-publish
  75 ;; M-x org-publish-all
  76 ;; M-x org-publish-current-file
  77 ;; M-x org-publish-current-project
  78
  79 ;;;; Simple example configuration:
  80
  81 ;; (setq org-publish-project-alist
  82 ;;       (list
  83 ;;        '("org" . (:base-directory "~/org/"
  84 ;;                   :base-extension "org"
  85 ;;                   :publishing-directory "~/public_html"
  86 ;;                   :with-section-numbers nil
  87 ;;                   :table-of-contents nil
  88 ;;                   :style "<link rel=stylesheet href=\"../other/mystyle.css\" type=\"text/css\">")))
  89
  90 ;;;; More complex example configuration:
  91
  92 ;; Imagine your *.org files are kept in ~/org, your images in
  93 ;; ~/images, and stylesheets in ~/other. Now imagine you want to
  94 ;; publish the files through an ssh connection to a remote host, via
  95 ;; Tramp-mode. To maintain relative links from *.org files to /images
  96 ;; and /other, we should replicate the same directory structure in
  97 ;; your web server account's designated html root (in this case,
  98 ;; assumed to be ~/html)
  99
 100 ;; Once you've done created the proper directories, you can adapt the
 101 ;; following example configuration to your specific paths, run M-x
 102 ;; org-publish-all, and it should publish the files to the correct
 103 ;; directories on the web server, transforming the *.org files into
 104 ;; HTML, and leaving other files alone.
 105
 106 ;; (setq org-publish-project-alist
 107 ;;       (list
 108 ;;        '("orgfiles" :base-directory "~/org/"
 109 ;;                     :base-extension "org"
 110 ;;                     :publishing-directory "/ssh:user@host:~/html/notebook/"
 111 ;;                     :publishing-function org-publish-org-to-html
 112 ;;                     :exclude "PrivatePage.org"   ;; regexp
 113 ;;                     :headline-levels 3
 114 ;;                     :with-section-numbers nil
 115 ;;                     :table-of-contents nil
 116 ;;                     :style "<link rel=stylesheet href=\"../other/mystyle.css\" type=\"text/css\">"
 117 ;;                     :auto-preamble t
 118 ;;                     :auto-postamble nil)
 119 ;;
 120 ;;         ("images" :base-directory "~/images/"
 121 ;;                   :base-extension "jpg\\|gif\\|png"
 122 ;;                   :publishing-directory "/ssh:user@host:~/html/images/"
 123 ;;                   :publishing-function org-publish-attachment)
 124 ;;
 125 ;;         ("other"  :base-directory "~/other/"
 126 ;;                   :base-extension "css"
 127 ;;                   :publishing-directory "/ssh:user@host:~/html/other/"
 128 ;;                   :publishing-function org-publish-attachment)
 129 ;;         ("website" :components ("orgfiles" "images" "other"))))
 130
 131 ;; For more information, see the documentation for the variable
 132 ;; `org-publish-project-alist'.
 133
 134 ;; Of course, you don't have to publish to remote directories from
 135 ;; within emacs. You can always just publish to local folders, and
 136 ;; then use the synchronization/upload tool of your choice.
 137
 138
 139 ;;; List of user-visible changes since version 1.27
 140
 141 ;; 1.65: Remove old "composite projects". They're redundant.
 142 ;; 1.64: Allow meta-projects with :components
 143 ;; 1.57: Timestamps flag is now called "org-publish-use-timestamps-flag"
 144 ;; 1.52: Properly set default for :index-filename
 145 ;; 1.48: Composite projects allowed.
 146 ;;       :include keyword allowed.
 147 ;; 1.43: Index no longer includes itself in the index.
 148 ;; 1.42: Fix "function definition is void" error
 149 ;;       when :publishing-function not set in org-publish-current-file.
 150 ;; 1.41: Fixed bug where index isn't published on first try.
 151 ;; 1.37: Added interactive function "org-publish". Prompts for particular
 152 ;;       project name to publish.
 153 ;; 1.34: Added force-publish option to all interactive functions.
 154 ;; 1.32: Fixed "index.org has changed on disk" error during index publishing.
 155 ;; 1.30: Fixed startup error caused by (require 'em-unix)
 156
 157 ;;; Code:
 158
 159 (eval-when-compile
 160   (require 'cl))
 161
 162 (defgroup org-publish nil
 163         "Options for publishing a set of Org-mode and related files."
 164    :tag "Org Publishing"
 165    :group 'org)
 166
 167
 168 (defcustom org-publish-project-alist nil
 169   "Association list to control publishing behavior.
 170 Each element of the alist is a publishing 'project.'  The CAR of
 171 each element is a string, uniquely identifying the project. The
 172 CDR of each element is in one of the following forms:
 173
 174   (:property value :property value ... )
 175
 176 OR,
 177
 178   (:components (\"project-1\" \"project-2\" ...))
 179
 180 When the CDR of an element of org-publish-project-alist is in
 181 this second form, the elements of the list after :components are
 182 taken to be components of the project, which group together files
 183 requiring different publishing options. When you publish such a
 184 project with M-x org-publish, the components all publish.
 185
 186 When a property is given a value in org-publish-project-alist, its
 187 setting overrides the value of the corresponding user variable
 188  (if any) during publishing. However, options set within a file
 189 override everything.
 190
 191 Most properties are optional, but some should always be set:
 192
 193     :base-directory        Directory containing publishing source files
 194     :base-extension        Extension (without the dot!) of source files.
 195                              This can be a regular expression.
 196     :publishing-directory  Directory (possibly remote) where output
 197                              files will be published
 198
 199 The :exclude property may be used to prevent certain files from
 200 being published. Its value may be a string or regexp matching
 201 file names you don't want to be published.
 202
 203 The :include property may be used to include extra files. Its
 204 value may be a list of filenames to include. The filenames are
 205 considered relative to the publishing directory.
 206
 207 When both :include and :exclude properties are given values, the
 208 exclusion step happens first.
 209
 210 One special property controls which back-end function to use for
 211 publishing files in the project. This can be used to extend the
 212 set of file types publishable by org-publish, as well as the set
 213 of output formats.
 214
 215     :publishing-function   Function to publish file. The default is
 216                              org-publish-org-to-html, but other
 217                              values are possible.
 218
 219 Some properties control details of the Org publishing process,
 220 and are equivalent to the corresponding user variables listed in
 221 the right column. See the documentation for those variables to
 222 learn more about their use and default values.
 223
 224     :language              org-export-default-language
 225     :headline-levels       org-export-headline-levels
 226     :section-numbers       org-export-with-section-numbers
 227     :table-of-contents     org-export-with-toc
 228     :emphasize             org-export-with-emphasize
 229     :sub-superscript       org-export-with-sub-superscripts
 230     :TeX-macros            org-export-with-TeX-macros
 231     :fixed-width           org-export-with-fixed-width
 232     :tables                org-export-with-tables
 233     :table-auto-headline   org-export-highlight-first-table-line
 234     :style                 org-export-html-style
 235     :convert-org-links     org-export-html-link-org-files-as-html
 236     :inline-images         org-export-html-inline-images
 237     :expand-quoted-html    org-export-html-expand
 238     :timestamp             org-export-html-with-timestamp
 239     :publishing-directory  org-export-publishing-directory
 240     :preamble              org-export-html-preamble
 241     :postamble             org-export-html-postamble
 242     :auto-preamble         org-export-html-auto-preamble
 243     :auto-postamble        org-export-html-auto-postamble
 244     :author                user-full-name
 245     :email                 user-mail-address
 246
 247 The following properties may be used to control publishing of an
 248 index of files or summary page for a given project.
 249
 250     :auto-index            Whether to publish an index during
 251                            org-publish-current-project or org-publish-all.
 252     :index-filename        Filename for output of index. Defaults
 253                            to 'index.org' (which becomes 'index.html')
 254     :index-title           Title of index page. Defaults to name of file.
 255     :index-function        Plugin function to use for generation of index.
 256                            Defaults to 'org-publish-org-index', which
 257                            generates a plain list of links to all files
 258                            in the project.
 259 "
 260   :group 'org-publish
 261   :type 'alist)
 262
 263
 264 (defcustom org-publish-use-timestamps-flag t
 265   "When non-nil, use timestamp checking to publish only changed files.
 266 When nil, do no timestamp checking and always publish all
 267 files."
 268   :group 'org-publish
 269   :type 'boolean)
 270
 271
 272 (defcustom org-publish-timestamp-directory "~/.org-timestamps/"
 273   "Name of directory in which to store publishing timestamps."
 274   :group 'org-publish
 275   :type 'string)
 276
 277
 278 ;;;; Timestamp-related functions
 279
 280
 281 (defun org-publish-timestamp-filename (filename)
 282   "Return path to timestamp file for filename FILENAME."
 283   (while (string-match "~\\|/" filename)
 284     (setq filename (replace-match "_" nil t filename)))
 285   (concat org-publish-timestamp-directory filename ".timestamp"))
 286
 287
 288 (defun org-publish-needed-p (filename)
 289   "Check whether file should be published.
 290 If org-publish-use-timestamps-flag is set to nil, this function always
 291 returns t. Otherwise, check the timestamps folder to determine
 292 whether file should be published."
 293   (if org-publish-use-timestamps-flag
 294       (progn
 295         ;;
 296         ;; create folder if needed
 297         (if (not (file-exists-p org-publish-timestamp-directory))
 298             (make-directory org-publish-timestamp-directory)
 299           (if (not (file-directory-p org-publish-timestamp-directory))
 300               (error "org-publish-timestamp-directory must be a directory.")))
 301         ;;
 302         ;; check timestamp. ok if timestamp file doesn't exist
 303         (let* ((timestamp (org-publish-timestamp-filename filename))
 304                (rtn (file-newer-than-file-p filename timestamp)))
 305           (if rtn
 306               ;; handle new timestamps
 307               (if (not (file-exists-p timestamp))
 308                   ;; create file
 309                   (with-temp-buffer
 310                     (write-file timestamp)
 311                     (kill-buffer (current-buffer)))))
 312           rtn))
 313     t))
 314
 315
 316 (defun org-publish-update-timestamp (filename)
 317   "Update publishing timestamp for file FILENAME."
 318   (let ((timestamp (org-publish-timestamp-filename filename)))
 319     (set-file-times timestamp)))
 320
 321
 322 ;;;; Getting project information out of org-publish-project-alist
 323
 324
 325 (defun org-publish-get-plists (&optional project-name)
 326   "Return a list of property lists for project PROJECT-NAME.
 327 When argument is not given, return all property lists for all projects."
 328   (let ((alist (if project-name
 329                    (list (assoc project-name org-publish-project-alist))
 330                  org-publish-project-alist))
 331         (project nil)
 332         (plists nil)
 333         (components nil))
 334     (while (setq project (pop alist))
 335       (if (setq components (plist-get (cdr project) :components))
 336           ;; meta project. annotate each plist with name of enclosing project
 337           (setq plists
 338                 (append plists
 339                         (mapcar (lambda (p)
 340                                   (plist-put p :project-name (car project)))
 341                                 (mapcan 'org-publish-get-plists components))))
 342         ;; normal project
 343         (let ((p (cdr project)))
 344           (setq p (plist-put p :project-name (car project)))
 345           (setq plists (append plists (list (cdr project)))))))
 346     ;;
 347     plists))
 348
 349
 350 (defun org-publish-get-base-files (plist &optional exclude-regexp)
 351   "Return a list of all files in project defined by PLIST.
 352 If EXCLUDE-REGEXP is set, this will be used to filter out
 353 matching filenames."
 354   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 355          (include-list (plist-get plist :include))
 356          (extension (or (plist-get plist :base-extension) "org"))
 357          (regexp (concat "^[^\\.].*\\.\\(" extension "\\)$"))
 358          (allfiles (directory-files dir t regexp)))
 359     ;;
 360     ;; exclude files
 361     (setq allfiles
 362           (if (not exclude-regexp)
 363               allfiles
 364             (delq nil
 365                   (mapcar (lambda (x)
 366                             (if (string-match exclude-regexp x) nil x))
 367                           allfiles))))
 368     ;;
 369     ;; include extra files
 370     (let ((inc nil))
 371       (while (setq inc (pop include-list))
 372         (setq allfiles (cons (concat dir inc) allfiles))))
 373
 374     allfiles))
 375
 376
 377 (defun org-publish-get-project-from-filename (filename)
 378   "Figure out which project a given FILENAME belongs to, if any.
 379 Filename should contain full path. Returns name of project, or
 380 nil if not found."
 381   (let ((found nil))
 382     (mapcar
 383      (lambda (plist)
 384        (let ((files (org-publish-get-base-files plist)))
 385          (if (member (expand-file-name filename) files)
 386              (setq found (plist-get plist :project-name)))))
 387      (org-publish-get-plists))
 388     found))
 389
 390
 391 (defun org-publish-get-plist-from-filename (filename)
 392   "Return publishing configuration plist for file FILENAME."
 393   (let ((found nil))
 394     (mapcar
 395      (lambda (plist)
 396        (let ((files (org-publish-get-base-files plist)))
 397          (if (member (expand-file-name filename) files)
 398              (setq found plist))))
 399      (org-publish-get-plists))
 400     found))
 401
 402
 403 ;;;; Pluggable publishing back-end functions
 404
 405
 406 (defun org-publish-org-to-html (plist filename)
 407   "Publish an org file to HTML.
 408 PLIST is the property list for the given project.
 409 FILENAME is the filename of the org file to be published."
 410   (require 'org)
 411   (let* ((arg (plist-get plist :headline-levels)))
 412     (progn
 413       (find-file filename)
 414       (org-export-as-html arg nil plist)
 415       ;; get rid of HTML buffer
 416       (kill-buffer (current-buffer)))))
 417
 418
 419 (defun org-publish-attachment (plist filename)
 420   "Publish a file with no transformation of any kind.
 421 PLIST is the property list for the given project.
 422 FILENAME is the filename of the file to be published."
 423   ;; make sure eshell/cp code is loaded
 424   (require 'eshell)
 425   (require 'esh-maint)
 426   (require 'em-unix)
 427   (let ((destination (file-name-as-directory (plist-get plist :publishing-directory))))
 428     (eshell/cp filename destination)))
 429
 430
 431 ;;;; Publishing files, sets of files, and indices
 432
 433
 434 (defun org-publish-file (filename)
 435   "Publish file FILENAME."
 436   (let* ((project-name (org-publish-get-project-from-filename filename))
 437          (plist (org-publish-get-plist-from-filename filename))
 438          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html)))
 439     (if (not project-name)
 440         (error (format "File %s is not part of any known project." filename)))
 441     (when (org-publish-needed-p filename)
 442       (funcall publishing-function plist filename)
 443       (org-publish-update-timestamp filename))))
 444
 445
 446 (defun org-publish-plist (plist)
 447   "Publish all files in set defined by PLIST.
 448  If :auto-index is set, publish the index too."
 449   (let* ((exclude-regexp (plist-get plist :exclude))
 450          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html))
 451          (index-p (plist-get plist :auto-index))
 452          (index-filename (or (plist-get plist :index-filename) "index.org"))
 453          (index-function (or (plist-get plist :index-function) 'org-publish-org-index))
 454          (f nil))
 455     ;;
 456     (if index-p
 457         (funcall index-function plist index-filename))
 458     (let ((files (org-publish-get-base-files plist exclude-regexp)))
 459       (while (setq f (pop files))
 460         ;; check timestamps
 461         (when (org-publish-needed-p f)
 462           (funcall publishing-function plist f)
 463           (org-publish-update-timestamp f))))))
 464
 465
 466 (defun org-publish-org-index (plist &optional index-filename)
 467   "Create an index of pages in set defined by PLIST.
 468 Optionally set the filename of the index with INDEX-FILENAME;
 469 default is 'index.org'."
 470   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 471          (exclude-regexp (plist-get plist :exclude))
 472          (files (org-publish-get-base-files plist exclude-regexp))
 473          (index-filename (concat dir (or index-filename "index.org")))
 474          (index-buffer (find-buffer-visiting index-filename))
 475          (ifn (file-name-nondirectory index-filename))
 476          (f nil))
 477     ;;
 478     ;; if buffer is already open, kill it to prevent error message
 479     (if index-buffer
 480         (kill-buffer index-buffer))
 481     (with-temp-buffer
 482       (while (setq f (pop files))
 483         (let ((fn (file-name-nondirectory f)))
 484           (unless (string= fn ifn) ;; index shouldn't index itself
 485             (insert (concat " + [[file:" fn "]["
 486                             (file-name-sans-extension fn)
 487                             "]]\n")))))
 488       (write-file index-filename)
 489       (kill-buffer (current-buffer)))))
 490
 491
 492 ;(defun org-publish-meta-index (meta-plist &optional index-filename)
 493 ;  "Create an index for a metaproject."
 494 ;  (let* ((plists (
 495
 496
 497 ;;;; Interactive publishing functions
 498
 499
 500 ;;;###autoload
 501 (defun org-publish (project-name &optional force)
 502   "Publish the project PROJECT-NAME."
 503   (interactive "sProject name: \nP")
 504   (let ((org-publish-use-timestamps-flag (if force nil t))
 505         (plists (org-publish-get-plists project-name)))
 506     (mapcar 'org-publish-plist plists)))
 507
 508
 509 ;;;###autoload
 510 (defun org-publish-current-project (&optional force)
 511   "Publish the project associated with the current file.
 512 With prefix argument, force publishing all files in project."
 513   (interactive "P")
 514   (let* ((project-name (org-publish-get-project-from-filename (buffer-file-name)))
 515          (org-publish-use-timestamps-flag (if force nil t)))
 516     (if (not project-name)
 517         (error (format "File %s is not part of any known project." (buffer-file-name))))
 518     (org-publish project-name)))
 519
 520
 521 ;;;###autoload
 522 (defun org-publish-current-file (&optional force)
 523   "Publish the current file.
 524 With prefix argument, force publish the file."
 525   (interactive "P")
 526   (let ((org-publish-use-timestamps-flag
 527          (if force nil t)))
 528     (org-publish-file (buffer-file-name))))
 529
 530
 531 ;;;###autoload
 532 (defun org-publish-all (&optional force)
 533   "Publish all projects.
 534 With prefix argument, force publish all files."
 535   (interactive "P")
 536   (let ((org-publish-use-timestamps-flag
 537          (if force nil t))
 538         (plists (org-publish-get-plists)))
 539     (mapcar 'org-publish-plist plists)))
 540
 541
 542
 543 (provide 'org-publish)
 544 ;;; org-publish.el ends here