org-publish.el

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