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.80 2007/03/22 02:31:03 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.78: Allow list-valued :publishing-function
 142 ;; 1.77: Added :preparation-function, this allows you to use GNU Make etc.
 143 ;; 1.65: Remove old "composite projects". They're redundant.
 144 ;; 1.64: Allow meta-projects with :components
 145 ;; 1.57: Timestamps flag is now called "org-publish-use-timestamps-flag"
 146 ;; 1.52: Properly set default for :index-filename
 147 ;; 1.48: Composite projects allowed.
 148 ;;       :include keyword allowed.
 149 ;; 1.43: Index no longer includes itself in the index.
 150 ;; 1.42: Fix "function definition is void" error
 151 ;;       when :publishing-function not set in org-publish-current-file.
 152 ;; 1.41: Fixed bug where index isn't published on first try.
 153 ;; 1.37: Added interactive function "org-publish". Prompts for particular
 154 ;;       project name to publish.
 155 ;; 1.34: Added force-publish option to all interactive functions.
 156 ;; 1.32: Fixed "index.org has changed on disk" error during index publishing.
 157 ;; 1.30: Fixed startup error caused by (require 'em-unix)
 158
 159 ;;; Code:
 160
 161 (eval-when-compile
 162   (require 'cl))
 163
 164 (defgroup org-publish nil
 165         "Options for publishing a set of Org-mode and related files."
 166    :tag "Org Publishing"
 167    :group 'org)
 168
 169
 170 (defcustom org-publish-project-alist nil
 171   "Association list to control publishing behavior.
 172 Each element of the alist is a publishing 'project.'  The CAR of
 173 each element is a string, uniquely identifying the project. The
 174 CDR of each element is in one of the following forms:
 175
 176   (:property value :property value ... )
 177
 178 OR,
 179
 180   (:components (\"project-1\" \"project-2\" ...))
 181
 182 When the CDR of an element of org-publish-project-alist is in
 183 this second form, the elements of the list after :components are
 184 taken to be components of the project, which group together files
 185 requiring different publishing options. When you publish such a
 186 project with M-x org-publish, the components all publish.
 187
 188 When a property is given a value in org-publish-project-alist, its
 189 setting overrides the value of the corresponding user variable
 190  (if any) during publishing. However, options set within a file
 191 override everything.
 192
 193 Most properties are optional, but some should always be set:
 194
 195     :base-directory        Directory containing publishing source files
 196     :base-extension        Extension (without the dot!) of source files.
 197                              This can be a regular expression.
 198     :publishing-directory  Directory (possibly remote) where output
 199                              files will be published
 200
 201 The :exclude property may be used to prevent certain files from
 202 being published. Its value may be a string or regexp matching
 203 file names you don't want to be published.
 204
 205 The :include property may be used to include extra files. Its
 206 value may be a list of filenames to include. The filenames are
 207 considered relative to the publishing directory.
 208
 209 When both :include and :exclude properties are given values, the
 210 exclusion step happens first.
 211
 212 One special property controls which back-end function to use for
 213 publishing files in the project. This can be used to extend the
 214 set of file types publishable by org-publish, as well as the set
 215 of output formats.
 216
 217     :publishing-function     Function to publish file. The default is
 218                              org-publish-org-to-html, but other
 219                              values are possible. May also be a
 220                              list of functions, in which case
 221                              each function in the list is invoked
 222                              in turn.
 223
 224 Another property allows you to insert code that prepares a
 225 project for publishing. For example, you could call GNU Make on a
 226 certain makefile, to ensure published files are built up to date.
 227
 228     :preparation-function   Function to be called before publishing
 229                               this project.
 230
 231 Some properties control details of the Org publishing process,
 232 and are equivalent to the corresponding user variables listed in
 233 the right column. See the documentation for those variables to
 234 learn more about their use and default values.
 235
 236     :language              org-export-default-language
 237     :headline-levels       org-export-headline-levels
 238     :section-numbers       org-export-with-section-numbers
 239     :table-of-contents     org-export-with-toc
 240     :emphasize             org-export-with-emphasize
 241     :sub-superscript       org-export-with-sub-superscripts
 242     :TeX-macros            org-export-with-TeX-macros
 243     :fixed-width           org-export-with-fixed-width
 244     :tables                org-export-with-tables
 245     :table-auto-headline   org-export-highlight-first-table-line
 246     :style                 org-export-html-style
 247     :convert-org-links     org-export-html-link-org-files-as-html
 248     :inline-images         org-export-html-inline-images
 249     :expand-quoted-html    org-export-html-expand
 250     :timestamp             org-export-html-with-timestamp
 251     :publishing-directory  org-export-publishing-directory
 252     :preamble              org-export-html-preamble
 253     :postamble             org-export-html-postamble
 254     :auto-preamble         org-export-html-auto-preamble
 255     :auto-postamble        org-export-html-auto-postamble
 256     :author                user-full-name
 257     :email                 user-mail-address
 258
 259 The following properties may be used to control publishing of an
 260 index of files or summary page for a given project.
 261
 262     :auto-index            Whether to publish an index during
 263                            org-publish-current-project or org-publish-all.
 264     :index-filename        Filename for output of index. Defaults
 265                            to 'index.org' (which becomes 'index.html')
 266     :index-title           Title of index page. Defaults to name of file.
 267     :index-function        Plugin function to use for generation of index.
 268                            Defaults to 'org-publish-org-index', which
 269                            generates a plain list of links to all files
 270                            in the project.
 271 "
 272   :group 'org-publish
 273   :type 'alist)
 274
 275
 276 (defcustom org-publish-use-timestamps-flag t
 277   "When non-nil, use timestamp checking to publish only changed files.
 278 When nil, do no timestamp checking and always publish all
 279 files."
 280   :group 'org-publish
 281   :type 'boolean)
 282
 283
 284 (defcustom org-publish-timestamp-directory "~/.org-timestamps/"
 285   "Name of directory in which to store publishing timestamps."
 286   :group 'org-publish
 287   :type 'string)
 288
 289
 290 ;;;; Timestamp-related functions
 291
 292
 293 (defun org-publish-timestamp-filename (filename)
 294   "Return path to timestamp file for filename FILENAME."
 295   (while (string-match "~\\|/" filename)
 296     (setq filename (replace-match "_" nil t filename)))
 297   (concat org-publish-timestamp-directory filename ".timestamp"))
 298
 299
 300 (defun org-publish-needed-p (filename)
 301   "Check whether file should be published.
 302 If org-publish-use-timestamps-flag is set to nil, this function always
 303 returns t. Otherwise, check the timestamps folder to determine
 304 whether file should be published."
 305   (if org-publish-use-timestamps-flag
 306       (progn
 307         ;;
 308         ;; create folder if needed
 309         (if (not (file-exists-p org-publish-timestamp-directory))
 310             (make-directory org-publish-timestamp-directory)
 311           (if (not (file-directory-p org-publish-timestamp-directory))
 312               (error "org-publish-timestamp-directory must be a directory.")))
 313         ;;
 314         ;; check timestamp. ok if timestamp file doesn't exist
 315         (let* ((timestamp (org-publish-timestamp-filename filename))
 316                (rtn (file-newer-than-file-p filename timestamp)))
 317           (if rtn
 318               ;; handle new timestamps
 319               (if (not (file-exists-p timestamp))
 320                   ;; create file
 321                   (with-temp-buffer
 322                     (make-directory (file-name-directory timestamp) :parents)
 323                     (write-file timestamp)
 324                     (kill-buffer (current-buffer)))))
 325           rtn))
 326     t))
 327
 328
 329 (defun org-publish-update-timestamp (filename)
 330   "Update publishing timestamp for file FILENAME."
 331   (let ((timestamp (org-publish-timestamp-filename filename)))
 332     ;; Emacs 21 doesn't have set-file-times
 333     (if (fboundp 'set-file-times)
 334         (set-file-times timestamp)
 335       (call-process "touch" nil 0 nil timestamp))))
 336
 337
 338 ;;;; A hash mapping files to project names
 339
 340
 341 (defvar org-publish-files (make-hash-table :test 'equal) "Hash
 342 table mapping file names to project names.")
 343
 344
 345 ;;;; Checking filenames against this hash
 346
 347
 348 (defun org-publish-validate-link (link &optional directory)
 349   (gethash (file-truename (expand-file-name link directory))
 350            org-publish-files))
 351
 352
 353 ;;;; Getting project information out of org-publish-project-alist
 354
 355
 356 (defun org-publish-get-plists (&optional project-name)
 357  "Return a list of property lists for project PROJECT-NAME.
 358 When argument is not given, return all property lists for all projects."
 359  (let ((alist (if project-name
 360                    (list (assoc project-name org-publish-project-alist))
 361                  org-publish-project-alist))
 362         (project nil)
 363         (plists nil)
 364         (single nil)
 365         (components nil))
 366
 367    ;;
 368    ;;
 369    (while (setq project (pop alist))
 370      ;; what kind of project is it?
 371      (if (setq components (plist-get (cdr project) :components))
 372           ;; meta project. annotate each plist with name of enclosing project
 373           (setq single
 374                 (apply 'append
 375                        (mapcar 'org-publish-get-plists components)))
 376         ;; normal project
 377         (setq single (list (cdr project))))
 378      ;;
 379      (setq plists (append plists single))
 380      (dolist (p single)
 381         (let* ((exclude (plist-get p :exclude))
 382                (files (org-publish-get-base-files p exclude)))
 383           (dolist (f files)
 384             (puthash (file-truename f) (car project) org-publish-files)))))
 385    plists))
 386
 387
 388
 389 (defun org-publish-get-base-files (plist &optional exclude-regexp)
 390   "Return a list of all files in project defined by PLIST.
 391 If EXCLUDE-REGEXP is set, this will be used to filter out
 392 matching filenames."
 393   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 394          (include-list (plist-get plist :include))
 395          (extension (or (plist-get plist :base-extension) "org"))
 396          (regexp (concat "^[^\\.].*\\.\\(" extension "\\)$"))
 397          (allfiles (directory-files dir t regexp)))
 398     ;;
 399     ;; exclude files
 400     (setq allfiles
 401           (if (not exclude-regexp)
 402               allfiles
 403             (delq nil
 404                   (mapcar (lambda (x)
 405                             (if (string-match exclude-regexp x) nil x))
 406                           allfiles))))
 407     ;;
 408     ;; include extra files
 409     (let ((inc nil))
 410       (while (setq inc (pop include-list))
 411         (setq allfiles (cons (expand-file-name inc dir) allfiles))))
 412
 413     allfiles))
 414
 415
 416 (defun org-publish-get-project-from-filename (filename)
 417   "Figure out which project a given FILENAME belongs to, if any.
 418 Filename should contain full path. Returns name of project, or
 419 nil if not found."
 420   (org-publish-get-plists)
 421   (gethash (file-truename filename) org-publish-files))
 422
 423
 424 (defun org-publish-get-plist-from-filename (filename)
 425   "Return publishing configuration plist for file FILENAME."
 426   (let ((found nil))
 427     (mapcar
 428      (lambda (plist)
 429        (let ((files (org-publish-get-base-files plist)))
 430          (if (member (expand-file-name filename) files)
 431              (setq found plist))))
 432      (org-publish-get-plists))
 433     found))
 434
 435
 436
 437 ;;;; Pluggable publishing back-end functions
 438
 439
 440 (defun org-publish-org-to-html (plist filename)
 441   "Publish an org file to HTML.
 442 PLIST is the property list for the given project.
 443 FILENAME is the filename of the org file to be published."
 444   (require 'org)
 445   (let* ((arg (plist-get plist :headline-levels)))
 446     (progn
 447       (find-file filename)
 448       (org-export-as-html arg nil plist)
 449       ;; get rid of HTML buffer
 450       (kill-buffer (current-buffer)))))
 451
 452
 453 (defun org-publish-attachment (plist filename)
 454   "Publish a file with no transformation of any kind.
 455 PLIST is the property list for the given project.
 456 FILENAME is the filename of the file to be published."
 457   ;; make sure eshell/cp code is loaded
 458   (require 'eshell)
 459   (require 'esh-maint)
 460   (require 'em-unix)
 461   (let ((destination (file-name-as-directory (plist-get plist :publishing-directory))))
 462     (eshell/cp filename destination)))
 463
 464
 465 ;;;; Publishing files, sets of files, and indices
 466
 467
 468 (defun org-publish-file (filename)
 469   "Publish file FILENAME."
 470   (let* ((project-name (org-publish-get-project-from-filename filename))
 471          (plist (org-publish-get-plist-from-filename filename))
 472          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html)))
 473     (if (not project-name)
 474         (error (format "File %s is not part of any known project." filename)))
 475     (when (org-publish-needed-p filename)
 476       (if (listp publishing-function)
 477           ;; allow chain of publishing functions
 478           (mapc (lambda (f)
 479                   (funcall f plist filename))
 480                 publishing-function)
 481         (funcall publishing-function plist filename))
 482       (org-publish-update-timestamp filename))))
 483
 484
 485 (defun org-publish-plist (plist)
 486   "Publish all files in set defined by PLIST.
 487  If :auto-index is set, publish the index too."
 488   (let* ((exclude-regexp (plist-get plist :exclude))
 489          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html))
 490          (index-p (plist-get plist :auto-index))
 491          (index-filename (or (plist-get plist :index-filename) "index.org"))
 492          (index-function (or (plist-get plist :index-function) 'org-publish-org-index))
 493          (preparation-function (plist-get plist :preparation-function))
 494          (f nil))
 495     ;;
 496     (when preparation-function
 497       (funcall preparation-function))
 498     (if index-p
 499         (funcall index-function plist index-filename))
 500     (let ((files (org-publish-get-base-files plist exclude-regexp)))
 501       (while (setq f (pop files))
 502         ;; check timestamps
 503         (when (org-publish-needed-p f)
 504           (if (listp publishing-function)
 505               ;; allow chain of publishing functions
 506               (mapc (lambda (func)
 507                       (funcall func plist f))
 508                     publishing-function)
 509             (funcall publishing-function plist f))
 510           (org-publish-update-timestamp f))))))
 511
 512
 513 (defun org-publish-org-index (plist &optional index-filename)
 514   "Create an index of pages in set defined by PLIST.
 515 Optionally set the filename of the index with INDEX-FILENAME;
 516 default is 'index.org'."
 517   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 518          (exclude-regexp (plist-get plist :exclude))
 519          (files (org-publish-get-base-files plist exclude-regexp))
 520          (index-filename (concat dir (or index-filename "index.org")))
 521          (index-buffer (find-buffer-visiting index-filename))
 522          (ifn (file-name-nondirectory index-filename))
 523          (f nil))
 524     ;;
 525     ;; if buffer is already open, kill it to prevent error message
 526     (if index-buffer
 527         (kill-buffer index-buffer))
 528     (with-temp-buffer
 529       (while (setq f (pop files))
 530         (let ((fn (file-name-nondirectory f)))
 531           (unless (string= fn ifn) ;; index shouldn't index itself
 532             (insert (concat " + [[file:" fn "]["
 533                             (file-name-sans-extension fn)
 534                             "]]\n")))))
 535       (write-file index-filename)
 536       (kill-buffer (current-buffer)))))
 537
 538
 539 ;(defun org-publish-meta-index (meta-plist &optional index-filename)
 540 ;  "Create an index for a metaproject."
 541 ;  (let* ((plists (
 542
 543
 544 ;;;; Interactive publishing functions
 545
 546
 547 ;;;###autoload
 548 (defun org-publish (project-name &optional force)
 549   "Publish the project PROJECT-NAME."
 550   (interactive (list (completing-read "Project name: " org-publish-project-alist
 551                                       nil t)
 552                      current-prefix-arg))
 553   (save-window-excursion
 554     (let ((org-publish-use-timestamps-flag (if force nil t))
 555           (plists (org-publish-get-plists project-name)))
 556       (mapcar 'org-publish-plist plists))))
 557
 558
 559 ;;;###autoload
 560 (defun org-publish-current-project (&optional force)
 561   "Publish the project associated with the current file.
 562 With prefix argument, force publishing all files in project."
 563   (interactive "P")
 564   (save-window-excursion
 565     (let* ((project-name (org-publish-get-project-from-filename (buffer-file-name)))
 566            (org-publish-use-timestamps-flag (if force nil t)))
 567       (if (not project-name)
 568           (error (format "File %s is not part of any known project." (buffer-file-name))))
 569       (org-publish project-name))))
 570
 571
 572 ;;;###autoload
 573 (defun org-publish-current-file (&optional force)
 574   "Publish the current file.
 575 With prefix argument, force publish the file."
 576   (interactive "P")
 577   (save-window-excursion
 578     (let ((org-publish-use-timestamps-flag
 579            (if force nil t)))
 580       (org-publish-file (buffer-file-name)))))
 581
 582
 583 ;;;###autoload
 584 (defun org-publish-all (&optional force)
 585   "Publish all projects.
 586 With prefix argument, force publish all files."
 587   (interactive "P")
 588   (save-window-excursion
 589     (let ((org-publish-use-timestamps-flag
 590            (if force nil t))
 591           (plists (org-publish-get-plists)))
 592       (mapcar 'org-publish-plist plists))))
 593
 594
 595
 596 (provide 'org-publish)
 597 ;;; org-publish.el ends here