yeet-log

My blog, using org-publish
git clone https://git.git.jamzattack.xyz/yeet-log
Log | Files | Refs

org-publish.org (6340B)


      1 #+title: Using org-publish
      2 #+email: beardsleejamie@gmail.com
      3 #+date: <2020-06-20 Sat>
      4 
      5 * Excerpt from config file
      6 
      7 I use [[info:org#Publishing][org-publish]] for my websites.  This block has a lot going on:
      8 
      9 1. I set some [[my-org-publish-default-options][default options]] for publishing projects.
     10 2. I use a [[*Generate postamble][custom function]] to generate postamble.
     11 3. Include my three sites in [[help:org-publish-project-alist][org-publish-project-alist]].
     12 
     13 #+begin_src emacs-lisp
     14   (use-package ox-publish
     15     :defer t
     16     :config
     17     (use-package ox-jamzattack
     18       :demand
     19       :straight
     20       (ox-jamzattack :type git
     21                      :repo "git@jamzattack.xyz:ox-jamzattack.git"))
     22     <<my-org-html-postamble-format>>
     23     (defvar my-org-publish-default-options
     24       '(
     25         <<my-org-publish-default-options>>
     26         )
     27       "Default options for `org-publish-project-alist'.
     28 
     29   This variable must be spliced into `org-publish-project-alist'
     30   when set, i.e.
     31       (setq org-publish-project-alist
     32               `((\"project\"
     33                  ,@my-org-publish-default-options)))")
     34     (setq
     35      org-html-postamble t ; needed to use custom format
     36      org-export-headline-levels 6
     37      org-html-postamble-format
     38      (my-org-html-postamble-format
     39       "Author: %A")
     40      org-publish-timestamp-directory "~/.cache/org/timestamps/"
     41      org-html-head "<link rel=\"stylesheet\" type=\"text/css\" href=\"/style.css\"/>"
     42      org-publish-project-alist
     43      `(("blog"
     44         ,@my-org-publish-default-options
     45         :base-directory "~/jamzattack.xyz/blog"
     46         :with-toc t
     47         :publishing-directory "~/jamzattack.xyz/out/blog"
     48         :html-postamble-format ,(my-org-html-postamble-format
     49                                  "Author: %A"
     50                                  "Date: %d (modified %M)"
     51                                  "Top: <a href=\"/index.html\">The Yeet Log</a>")
     52         :sitemap-filename "index.org"
     53         :sitemap-title "The Yeet Log"
     54         :sitemap-format-entry
     55         (lambda (entry style project)
     56           (cond ((not (directory-name-p entry))
     57                  (format "%s [[file:%s][%s]]"
     58                          (format-time-string
     59                           "%Y-%m-%d"
     60                           (org-publish-find-date entry project))
     61                          entry
     62                          (org-publish-find-title entry project)))
     63                 ((eq style 'tree)
     64                  ;; Return only last subdir.
     65                  (file-name-nondirectory (directory-file-name entry)))
     66                 (t entry)))
     67         :sitemap-sort-files anti-chronologically)
     68        ("music"
     69         ,@my-org-publish-default-options
     70         :base-directory "~/jamzattack.xyz/music"
     71         :recursive t
     72         :html-postamble-format ,(my-org-html-postamble-format
     73                                  "Author: %A"
     74                                  "Top: <a href=\"/sitemap.html\">All projects</a>")
     75         :publishing-directory "~/jamzattack.xyz/out/music"
     76         :sitemap-title "My Music Projects")
     77        ("html"
     78         ,@my-org-publish-default-options
     79         :base-directory "~/jamzattack.xyz/html"
     80         :publishing-directory "~/jamzattack.xyz/out/html"))))
     81 #+end_src
     82 
     83 ** Generate postamble
     84 
     85 A little function to generate postamble.
     86 
     87 #+name: my-org-html-postamble-format
     88 #+begin_src emacs-lisp :tangle no
     89   (defun my-org-html-postamble-format (&rest args)
     90     "Generate an html postamble using ARGS.
     91 
     92   This generates a paragraph for each item in ARGS.  For format
     93   strings, see the docstring of `org-html-postamble-format'."
     94     (unless args
     95       (setq args '("Author: %a <%e>")))
     96     (list (list "en"
     97                 (mapconcat (lambda (str)
     98                              (format "<p>%s</p>" str))
     99                            args
    100                            "\n"))))
    101 #+end_src
    102 
    103 ** Default export options
    104 
    105 A list of default export options.
    106 
    107 #+name: my-org-publish-default-options
    108 #+begin_src emacs-lisp :tangle no
    109   :auto-sitemap t
    110   :publishing-function org-html-publish-to-html
    111   :html-metadata-timestamp-format "%Y-%m-%d"
    112   :with-toc nil
    113   :with-email t
    114   :with-drawers nil
    115   :section-numbers nil
    116   :with-todo-keywords nil
    117 #+end_src
    118 
    119 * [[https://git.jamzattack.xyz/ox-jamzattack][ox-jamzattack]]
    120 
    121 I wrote the library [[https://git.jamzattack.xyz/ox-jamzattack][ox-jamzattack]] in a vain attempt to make this
    122 section less dense, but it still has a lot going on.
    123 
    124 In [[https://git.jamzattack.xyz/ox-jamzattack][ox-jamzattack]], I define a formatting function to replace
    125 [[help:org-html-format-spec][org-html-format-spec]].  This allows me to extract the date that a file
    126 was last edited using [[https://git-scm.com][git]] (as seen at the bottom of this page).
    127 
    128 * Publishing locally or via TRAMP?
    129 
    130 I used to use TRAMP directories as the publishing directory for my
    131 website(s).  This is actually really simple, and can just be done as
    132 though they were local directories:
    133 
    134 #+begin_src emacs-lisp
    135   (setq org-publish-project-alist
    136         '(("blog"
    137            :base-directory "~/jamzattack.xyz/blog"
    138            :publishing-directory "/ssh:jamzattack.xyz:/var/www/blog")
    139           ("music"
    140            :base-directory "~/jamzattack.xyz/music"
    141            :publishing-directory "/ssh:jamzattack.xyz:/var/www/music")))
    142 #+end_src
    143 
    144 This worked fine for a while, but I found it kind of awkward if I
    145 needed to make additional edits.
    146 
    147 Now, I publish to a local directory and use [[https://rsync.samba.org/][rsync]] to send the files to
    148 my server:
    149 
    150 #+begin_src emacs-lisp
    151   (setq org-publish-project-alist
    152         '(("blog"
    153            :base-directory "~/jamzattack.xyz/blog"
    154            :publishing-directory "~/jamzattack.xyz/out/blog")
    155           ("music"
    156            :base-directory "~/jamzattack.xyz/music"
    157            :publishing-directory "~/jamzattack.xyz/out/music")))
    158 #+end_src
    159 
    160 #+begin_src shell
    161   rsync -rLv --exclude '*~' ~/jamzattack.xyz/out/* jamzattack.xyz:/var/www
    162 #+end_src
    163 
    164 This has a few benefits:
    165 1. I can check that everything works fine (links, images, etc.) before
    166    pushing to my server.
    167 2. I don't need to resort to any hackery to publish non-org files.
    168 3. I can use symlinks and have the server's directory mimic the local
    169    one.  This is really useful for publishing my [[https://music.jamzattack.xyz/sitemap.html][sheet music]].
    170 4. I have offline access to all the exported html files.