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.78 2006/09/10 06:41:23 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                     (write-file timestamp)
 323                     (kill-buffer (current-buffer)))))
 324           rtn))
 325     t))
 326
 327
 328 (defun org-publish-update-timestamp (filename)
 329   "Update publishing timestamp for file FILENAME."
 330   (let ((timestamp (org-publish-timestamp-filename filename)))
 331     ;; Emacs 21 doesn't have set-file-times
 332     (if (fboundp 'set-file-times)
 333         (set-file-times timestamp)
 334       (call-process "touch" nil 0 nil timestamp))))
 335
 336
 337 ;;;; A hash mapping files to project names
 338
 339
 340 (defvar org-publish-files (make-hash-table :test 'equal) "Hash
 341 table mapping file names to project names.")
 342
 343
 344 ;;;; Checking filenames against this hash
 345
 346
 347 (defun org-publish-validate-link (link &optional directory)
 348   (gethash (file-truename (expand-file-name link directory))
 349            org-publish-files))
 350
 351
 352 ;;;; Getting project information out of org-publish-project-alist
 353
 354
 355 (defun org-publish-get-plists (&optional project-name)
 356  "Return a list of property lists for project PROJECT-NAME.
 357 When argument is not given, return all property lists for all projects."
 358  (let ((alist (if project-name
 359                    (list (assoc project-name org-publish-project-alist))
 360                  org-publish-project-alist))
 361         (project nil)
 362         (plists nil)
 363         (single nil)
 364         (components nil))
 365
 366    ;;
 367    ;;
 368    (while (setq project (pop alist))
 369      ;; what kind of project is it?
 370      (if (setq components (plist-get (cdr project) :components))
 371           ;; meta project. annotate each plist with name of enclosing project
 372           (setq single
 373                 (apply 'append
 374                        (mapcar 'org-publish-get-plists components)))
 375         ;; normal project
 376         (setq single (list (cdr project))))
 377      ;;
 378      (setq plists (append plists single))
 379      (dolist (p single)
 380         (let* ((exclude (plist-get p :exclude))
 381                (files (org-publish-get-base-files p exclude)))
 382           (dolist (f files)
 383             (puthash (file-truename f) (car project) org-publish-files)))))
 384    plists))
 385
 386
 387
 388 (defun org-publish-get-base-files (plist &optional exclude-regexp)
 389   "Return a list of all files in project defined by PLIST.
 390 If EXCLUDE-REGEXP is set, this will be used to filter out
 391 matching filenames."
 392   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 393          (include-list (plist-get plist :include))
 394          (extension (or (plist-get plist :base-extension) "org"))
 395          (regexp (concat "^[^\\.].*\\.\\(" extension "\\)$"))
 396          (allfiles (directory-files dir t regexp)))
 397     ;;
 398     ;; exclude files
 399     (setq allfiles
 400           (if (not exclude-regexp)
 401               allfiles
 402             (delq nil
 403                   (mapcar (lambda (x)
 404                             (if (string-match exclude-regexp x) nil x))
 405                           allfiles))))
 406     ;;
 407     ;; include extra files
 408     (let ((inc nil))
 409       (while (setq inc (pop include-list))
 410         (setq allfiles (cons (expand-file-name inc dir) allfiles))))
 411
 412     allfiles))
 413
 414
 415 (defun org-publish-get-project-from-filename (filename)
 416   "Figure out which project a given FILENAME belongs to, if any.
 417 Filename should contain full path. Returns name of project, or
 418 nil if not found."
 419   (org-publish-get-plists)
 420   (gethash (file-truename filename) org-publish-files))
 421
 422
 423 (defun org-publish-get-plist-from-filename (filename)
 424   "Return publishing configuration plist for file FILENAME."
 425   (let ((found nil))
 426     (mapcar
 427      (lambda (plist)
 428        (let ((files (org-publish-get-base-files plist)))
 429          (if (member (expand-file-name filename) files)
 430              (setq found plist))))
 431      (org-publish-get-plists))
 432     found))
 433
 434
 435
 436 ;;;; Pluggable publishing back-end functions
 437
 438
 439 (defun org-publish-org-to-html (plist filename)
 440   "Publish an org file to HTML.
 441 PLIST is the property list for the given project.
 442 FILENAME is the filename of the org file to be published."
 443   (require 'org)
 444   (let* ((arg (plist-get plist :headline-levels)))
 445     (progn
 446       (find-file filename)
 447       (org-export-as-html arg nil plist)
 448       ;; get rid of HTML buffer
 449       (kill-buffer (current-buffer)))))
 450
 451
 452 (defun org-publish-attachment (plist filename)
 453   "Publish a file with no transformation of any kind.
 454 PLIST is the property list for the given project.
 455 FILENAME is the filename of the file to be published."
 456   ;; make sure eshell/cp code is loaded
 457   (require 'eshell)
 458   (require 'esh-maint)
 459   (require 'em-unix)
 460   (let ((destination (file-name-as-directory (plist-get plist :publishing-directory))))
 461     (eshell/cp filename destination)))
 462
 463
 464 ;;;; Publishing files, sets of files, and indices
 465
 466
 467 (defun org-publish-file (filename)
 468   "Publish file FILENAME."
 469   (let* ((project-name (org-publish-get-project-from-filename filename))
 470          (plist (org-publish-get-plist-from-filename filename))
 471          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html)))
 472     (if (not project-name)
 473         (error (format "File %s is not part of any known project." filename)))
 474     (when (org-publish-needed-p filename)
 475       (if (listp publishing-function)
 476           ;; allow chain of publishing functions
 477           (mapc (lambda (f)
 478                   (funcall f plist filename))
 479                 publishing-function)
 480         (funcall publishing-function plist filename))
 481       (org-publish-update-timestamp filename))))
 482
 483
 484 (defun org-publish-plist (plist)
 485   "Publish all files in set defined by PLIST.
 486  If :auto-index is set, publish the index too."
 487   (let* ((exclude-regexp (plist-get plist :exclude))
 488          (publishing-function (or (plist-get plist :publishing-function) 'org-publish-org-to-html))
 489          (index-p (plist-get plist :auto-index))
 490          (index-filename (or (plist-get plist :index-filename) "index.org"))
 491          (index-function (or (plist-get plist :index-function) 'org-publish-org-index))
 492          (preparation-function (plist-get plist :preparation-function))
 493          (f nil))
 494     ;;
 495     (when preparation-function
 496       (funcall preparation-function))
 497     (if index-p
 498         (funcall index-function plist index-filename))
 499     (let ((files (org-publish-get-base-files plist exclude-regexp)))
 500       (while (setq f (pop files))
 501         ;; check timestamps
 502         (when (org-publish-needed-p f)
 503           (if (listp publishing-function)
 504               ;; allow chain of publishing functions
 505               (mapc (lambda (func)
 506                       (funcall func plist f))
 507                     publishing-function)
 508             (funcall publishing-function plist f))
 509           (org-publish-update-timestamp f))))))
 510
 511
 512 (defun org-publish-org-index (plist &optional index-filename)
 513   "Create an index of pages in set defined by PLIST.
 514 Optionally set the filename of the index with INDEX-FILENAME;
 515 default is 'index.org'."
 516   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 517          (exclude-regexp (plist-get plist :exclude))
 518          (files (org-publish-get-base-files plist exclude-regexp))
 519          (index-filename (concat dir (or index-filename "index.org")))
 520          (index-buffer (find-buffer-visiting index-filename))
 521          (ifn (file-name-nondirectory index-filename))
 522          (f nil))
 523     ;;
 524     ;; if buffer is already open, kill it to prevent error message
 525     (if index-buffer
 526         (kill-buffer index-buffer))
 527     (with-temp-buffer
 528       (while (setq f (pop files))
 529         (let ((fn (file-name-nondirectory f)))
 530           (unless (string= fn ifn) ;; index shouldn't index itself
 531             (insert (concat " + [[file:" fn "]["
 532                             (file-name-sans-extension fn)
 533                             "]]\n")))))
 534       (write-file index-filename)
 535       (kill-buffer (current-buffer)))))
 536
 537
 538 ;(defun org-publish-meta-index (meta-plist &optional index-filename)
 539 ;  "Create an index for a metaproject."
 540 ;  (let* ((plists (
 541
 542
 543 ;;;; Interactive publishing functions
 544
 545
 546 ;;;###autoload
 547 (defun org-publish (project-name &optional force)
 548   "Publish the project PROJECT-NAME."
 549   (interactive (list (completing-read "Project name: " org-publish-project-alist
 550                                       nil t)
 551                      current-prefix-arg))
 552   (let ((org-publish-use-timestamps-flag (if force nil t))
 553         (plists (org-publish-get-plists project-name)))
 554     (mapcar 'org-publish-plist plists)))
 555
 556
 557 ;;;###autoload
 558 (defun org-publish-current-project (&optional force)
 559   "Publish the project associated with the current file.
 560 With prefix argument, force publishing all files in project."
 561   (interactive "P")
 562   (let* ((project-name (org-publish-get-project-from-filename (buffer-file-name)))
 563          (org-publish-use-timestamps-flag (if force nil t)))
 564     (if (not project-name)
 565         (error (format "File %s is not part of any known project." (buffer-file-name))))
 566     (org-publish project-name)))
 567
 568
 569 ;;;###autoload
 570 (defun org-publish-current-file (&optional force)
 571   "Publish the current file.
 572 With prefix argument, force publish the file."
 573   (interactive "P")
 574   (let ((org-publish-use-timestamps-flag
 575          (if force nil t)))
 576     (org-publish-file (buffer-file-name))))
 577
 578
 579 ;;;###autoload
 580 (defun org-publish-all (&optional force)
 581   "Publish all projects.
 582 With prefix argument, force publish all files."
 583   (interactive "P")
 584   (let ((org-publish-use-timestamps-flag
 585          (if force nil t))
 586         (plists (org-publish-get-plists)))
 587     (mapcar 'org-publish-plist plists)))
 588
 589
 590
 591 (provide 'org-publish)
 592 ;;; org-publish.el ends here