org-publish.el

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