org-publish.el

   1 ;;; org-publish.el --- publish related org-mode files as a website
   2
   3 ;; Copyright (C) 2006, 2007  Free Software Foundation, Inc.
   4
   5 ;; Author: David O'Toole <dto@gnu.org>
   6 ;; Keywords: hypermedia, outlines
   7 ;; Version: 1.80
   8
   9 ;; This file is free software; you can redistribute it and/or modify
  10 ;; it under the terms of the GNU General Public License as published by
  11 ;; the Free Software Foundation; either version 3, or (at your option)
  12 ;; any later version.
  13
  14 ;; This file is distributed in the hope that it will be useful,
  15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 ;; GNU General Public License for more details.
  18
  19 ;; You should have received a copy of the GNU General Public License
  20 ;; along with GNU Emacs; see the file COPYING.  If not, write to
  21 ;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22 ;; Boston, MA 02110-1301, USA.
  23
  24 ;; This file is part of GNU Emacs.
  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
 295 (defun org-publish-timestamp-filename (filename)
 296   "Return path to timestamp file for filename FILENAME."
 297   (while (string-match "~\\|/" filename)
 298     (setq filename (replace-match "_" nil t filename)))
 299   (concat org-publish-timestamp-directory filename ".timestamp"))
 300
 301
 302 (defun org-publish-needed-p (filename)
 303   "Check whether file should be published.
 304 If org-publish-use-timestamps-flag is set to nil, this function always
 305 returns t. Otherwise, check the timestamps folder to determine
 306 whether file should be published."
 307   (if org-publish-use-timestamps-flag
 308       (progn
 309         ;;
 310         ;; create folder if needed
 311         (if (not (file-exists-p org-publish-timestamp-directory))
 312             (make-directory org-publish-timestamp-directory)
 313           (if (not (file-directory-p org-publish-timestamp-directory))
 314               (error "org-publish-timestamp-directory must be a directory.")))
 315         ;;
 316         ;; check timestamp. ok if timestamp file doesn't exist
 317         (let* ((timestamp (org-publish-timestamp-filename filename))
 318                (rtn (file-newer-than-file-p filename timestamp)))
 319           (if rtn
 320               ;; handle new timestamps
 321               (if (not (file-exists-p timestamp))
 322                   ;; create file
 323                   (with-temp-buffer
 324                     (make-directory (file-name-directory timestamp) :parents)
 325                     (write-file timestamp)
 326                     (kill-buffer (current-buffer)))))
 327           rtn))
 328     t))
 329
 330
 331 (defun org-publish-update-timestamp (filename)
 332   "Update publishing timestamp for file FILENAME."
 333   (let ((timestamp (org-publish-timestamp-filename filename)))
 334     ;; Emacs 21 doesn't have set-file-times
 335     (if (fboundp 'set-file-times)
 336         (set-file-times timestamp)
 337       (call-process "touch" nil 0 nil timestamp))))
 338
 339
 340 ;;;; A hash mapping files to project names
 341
 342
 343 (defvar org-publish-files (make-hash-table :test 'equal) "Hash
 344 table mapping file names to project names.")
 345
 346
 347 ;;;; Checking filenames against this hash
 348
 349
 350 (defun org-publish-validate-link (link &optional directory)
 351   (gethash (file-truename (expand-file-name link directory))
 352            org-publish-files))
 353
 354
 355 ;;;; Getting project information out of org-publish-project-alist
 356
 357
 358 (defun org-publish-get-plists (&optional project-name)
 359  "Return a list of property lists for project PROJECT-NAME.
 360 When argument is not given, return all property lists for all projects."
 361  (let ((alist (if project-name
 362                    (list (assoc project-name org-publish-project-alist))
 363                  org-publish-project-alist))
 364         (project nil)
 365         (plists nil)
 366         (single nil)
 367         (components nil))
 368
 369    ;;
 370    ;;
 371    (while (setq project (pop alist))
 372      ;; what kind of project is it?
 373      (if (setq components (plist-get (cdr project) :components))
 374           ;; meta project. annotate each plist with name of enclosing project
 375           (setq single
 376                 (apply 'append
 377                        (mapcar 'org-publish-get-plists components)))
 378         ;; normal project
 379         (setq single (list (cdr project))))
 380      ;;
 381      (setq plists (append plists single))
 382      (dolist (p single)
 383         (let* ((exclude (plist-get p :exclude))
 384                (files (org-publish-get-base-files p exclude)))
 385           (dolist (f files)
 386             (puthash (file-truename f) (car project) org-publish-files)))))
 387    plists))
 388
 389
 390
 391 (defun org-publish-get-base-files (plist &optional exclude-regexp)
 392   "Return a list of all files in project defined by PLIST.
 393 If EXCLUDE-REGEXP is set, this will be used to filter out
 394 matching filenames."
 395   (let* ((dir (file-name-as-directory (plist-get plist :base-directory)))
 396          (include-list (plist-get plist :include))
 397          (extension (or (plist-get plist :base-extension) "org"))
 398          (regexp (concat "^[^\\.].*\\.\\(" extension "\\)$"))
 399          (allfiles (directory-files dir t regexp)))
 400     ;;
 401     ;; exclude files
 402     (setq allfiles
 403           (if (not exclude-regexp)
 404               allfiles
 405             (delq nil
 406                   (mapcar (lambda (x)
 407                             (if (string-match exclude-regexp x) nil x))
 408                           allfiles))))
 409     ;;
 410     ;; include extra files
 411     (let ((inc nil))
 412       (while (setq inc (pop include-list))
 413         (setq allfiles (cons (expand-file-name inc dir) allfiles))))
 414
 415     allfiles))
 416
 417
 418 (defun org-publish-get-project-from-filename (filename)
 419   "Figure out which project a given FILENAME belongs to, if any.
 420 Filename should contain full path. Returns name of project, or
 421 nil if not found."
 422   (org-publish-get-plists)
 423   (gethash (file-truename filename) org-publish-files))
 424
 425
 426 (defun org-publish-get-plist-from-filename (filename)
 427   "Return publishing configuration plist for file FILENAME."
 428   (let ((found nil))
 429     (mapcar
 430      (lambda (plist)
 431        (let ((files (org-publish-get-base-files plist)))
 432          (if (member (expand-file-name filename) files)
 433              (setq found plist))))
 434      (org-publish-get-plists))
 435     found))
 436
 437
 438
 439 ;;;; Pluggable publishing back-end functions
 440
 441 (defun org-publish-org-to-latex (plist filename)
 442   "Publish an org file to LaTeX."
 443   (org-publish-org-to "latex" plist filename))
 444
 445 (defun org-publish-org-to-html (plist filename)
 446   "Publish an org file to HTML."
 447   (org-publish-org-to "html" plist filename))
 448
 449 (defun org-publish-org-to (format plist filename)
 450   "Publish an org file to FORMAT.
 451 PLIST is the property list for the given project.
 452 FILENAME is the filename of the org file to be published."
 453   (require 'org)
 454   (let* ((arg (plist-get plist :headline-levels)))
 455     (progn
 456       (find-file filename)
 457       (funcall (intern (concat "org-export-as-" format))
 458                arg nil plist)
 459       (kill-buffer (current-buffer)))))
 460
 461
 462 (defun org-publish-attachment (plist filename)
 463   "Publish a file with no transformation of any kind.
 464 PLIST is the property list for the given project.
 465 FILENAME is the filename of the file to be published."
 466   ;; make sure eshell/cp code is loaded
 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 (format "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            (org-publish-use-timestamps-flag (if force nil t)))
 576       (if (not project-name)
 577           (error (format "File %s is not part of any known project." (buffer-file-name))))
 578       (org-publish project-name))))
 579
 580
 581 ;;;###autoload
 582 (defun org-publish-current-file (&optional force)
 583   "Publish the current file.
 584 With prefix argument, force publish the file."
 585   (interactive "P")
 586   (save-window-excursion
 587     (let ((org-publish-use-timestamps-flag
 588            (if force nil t)))
 589       (org-publish-file (buffer-file-name)))))
 590
 591
 592 ;;;###autoload
 593 (defun org-publish-all (&optional force)
 594   "Publish all projects.
 595 With prefix argument, force publish all files."
 596   (interactive "P")
 597   (save-window-excursion
 598     (let ((org-publish-use-timestamps-flag
 599            (if force nil t))
 600           (plists (org-publish-get-plists)))
 601       (mapcar 'org-publish-plist plists))))
 602
 603
 604
 605 (provide 'org-publish)
 606
 607 ;; arch-tag: 72807f3c-8af0-4a6b-8dca-c3376eb25adb
 608 ;;; org-publish.el ends here