#+TITLE: Setup
#+OPTIONS: toc:nil num:nil
#+COMMENTS: t
#+SLUG: setup
#+NO_SIDENOTES: t

* Introduction

/Last updated: <2025-12-18 Thu 22:00>/

See this link[fn:1] for a more generic introduction on how to publish websites using ~org-publish~.

This page will highlight the ~build-script.el~ used to generate this website. This entire website is generated through org files using the command:

#+BEGIN_SRC bash
emacs -Q --script build-site.el
#+END_SRC

* The script

The script is as follows, at the start I have some metadata relating to the file, followed by package management,then the declaration of variables/functions and finally the ~org-publish-project-alist~ which handles nearly all of the project generation instructions.

/The following code snippet will probably change often, as I can never seem to stick to a single configuration 😀/

#+BEGIN_SRC emacs-lisp
  ;;; build-site.el --- Publish my website using org-publish -*- lexical-binding: t; -*-

  ;; Author: Zaine Qayyum <zaineulabideen@outlook.com>
  ;; Created: 2025-08-08
  ;; Purpose: Build and publish my static site from Org files.

  ;;; Commentary:
  ;; Run this file with:
  ;; emacs -Q --script build-site.el

  ;;; Code:

  (require 'package)

  (add-to-list 'load-path "~/master-folder/org-platform/org_web/lisp/")

  (require 'recently-updated)
  (require 'tags)
  (require 'sidenotes)
  (require 'sitemaps)

  (setq package-user-dir (expand-file-name "./.packages"))
  (setq package-archives '(("melpa" . "https://melpa.org/packages/")
                           ("elpa" . "https://elpa.gnu.org/packages/")))

  (require 'ox-publish)
  (require 'cl-lib)
  (require 'org)
  (require 'ox)
  (require 'ox-html)

  (package-initialize)
  (unless package-archive-contents
    (package-refresh-contents))

  (package-install 'htmlize)
  (add-to-list 'load-path "~/master-folder/org-platform/org_web/")
  (require 'htmlize)

  (defvar z-shared-head
        "
  <link rel=\"stylesheet\" href=\"/assets/styles/style.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/bigger-picture.min.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/comments.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/kanban.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/org-syntax.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/misc.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/toc.css\" />
  <link rel=\"stylesheet\" href=\"/assets/styles/media.css\" />

  <script src=\"/assets/scripts/script.js\" defer></script> 
  <script src=\"/assets/scripts/competency-status-board.js\" defer></script> 
  <script src=\"/assets/scripts/comments.js\" defer></script> 
  <script src=\"/assets/scripts/bigger-picture.min.js\" defer></script>
  <script src=\"/assets/scripts/svg-pan-zoom.min.js\" defer></script>
  <script src=\"/assets/scripts/gallery-init.js\" defer></script>
  "
        )

  (setq org-export-global-macros
        (append
         '(("sidenote"
            . "@@html:<label for=\"sn$1\" class=\"margin-toggle sidenote-number\"></label><input type=\"checkbox\" id=\"sn$1\" class=\"margin-toggle\"/><span class=\"sidenote\">$2</span>@@")
  	 ("epigraph"  . "@@html:<div class=\"epigraph\"><blockquote>$1<footer>$2</footer></blockquote></div>@@")
  	 ("epigraph_single"  . "@@html:<div class=\"epigraph\"><blockquote>$1</blockquote></div>@@")
           ("epigraph3" . "@@html:<div class=\"epigraph\"><blockquote>$1<footer>$2, <cite>$3</cite></footer></blockquote></div>@@")
           ("kbd"       . "@@html:<kbd>$1</kbd>@@@@latex:\\texttt{$1}@@")
  	 ("margimg"
   . "@@html:<aside class=\"marginnote\"><figure class=\"mn-fig\"><img src=\"$1\" alt=\"$2\" class=\"mn-img\" loading=\"lazy\" decoding=\"async\"/>$3</figure></aside>@@")
  ("countdown" . "@@html:<time class=\"countdown\" datetime=\"$1\" data-label=\"$2\"></time>@@")

         
         org-export-global-macros)))


  (defvar z-preamble
    "
  <div class=\"banner-header\">
    <a href=\"/\"> <img src=\"/assets/images/gr.png\" alt=\"Site Logo\" class=\"banner-logo\" /> </a>
    <nav>
      <a href=\"/\">Home | </a>
      <a href=\"/blogs/2025/2025-list.html \">2025 | </a>
      <a href=\"/blogs/blogs-list.html\">Blogs | </a>
      <a href=\"/posts/career/career-list.html\">Career | </a>
      <a href=\"/home/services.html\">Services</a>
    </nav>
    <button class=\"theme-toggle\" id=\"theme-toggle\" type=\"button\" aria-label=\"Toggle dark mode\">🌗 Theme</button>
    </div>
    <div id=\"updated\">Updated: %C</div>

  "
  )

  (defvar z-postamble
    "<footer>
  <div class=\"copyright-container\">
  <div class=\"copyright\">
  Copyright &copy; 2022-2025 Zaine Qayyum. All rights reserved unless otherwise noted.</div></div>
  <div class=\"generated\">
  Created with %c on <a href=\"https://www.archlinux.org/\">Arch</a> <a href=\"https://www.gnu.org\">GNU</a>/<a href=\"https://www.kernel.org/\">Linux</a>
  </div>
  </footer>")



  (defun z/comments-file-p (file)
    "Return non-nil if FILE has comments enabled.
  A file has comments if:
    - It has a #+COMMENTS: keyword with value \"t\" (case-insensitive)."
    (when (file-exists-p file)
      (with-temp-buffer
        (insert-file-contents file)
        (org-mode)
        (let* ((keywords (org-collect-keywords '("COMMENTS")))
               (comments (cadr (assoc "COMMENTS" keywords))))
          (and comments
               (string-match-p "^\\s-*t\\s-*$"
                               (downcase comments)))))))

  (defun z/comments-file-slug (file)
    "Return page slug from #+SLUG: or fallback to filename."
    (with-temp-buffer
      (insert-file-contents file)
      (org-mode)
      (let* ((keywords (org-collect-keywords '("SLUG")))
             (slug (cadr (assoc "SLUG" keywords))))
        (if (and slug (string-match-p "\\S-" slug))
            slug
          (file-name-base file)))))

  (defun z/org-html-insert-comments-into-body (body backend info)
    "Insert comments section at the end of the document body."
    (when (org-export-derived-backend-p backend 'html)
      (let ((input-file (plist-get info :input-file)))
        (if (and input-file
                 (z/comments-file-p input-file))
            (let* ((slug (z/comments-file-slug input-file))
                   (comments-html
                    (format
                     "
  <section id=\"comments\" class=\"comments\" data-slug=\"%s\">
    <h2>Comments</h2>

    <div id=\"comments-list\" class=\"comments-list\">
      <noscript>Please enable JavaScript to view comments.</noscript>
    </div>

    <form id=\"comment-form\" class=\"comment-form\">
      <label class=\"comment-author\">
        <span>Name (optional)</span>
        <input type=\"text\" name=\"author\"/>
      </label>

      <label class=\"comment-content\">
        <span>Your comment</span>
        <textarea name=\"content\" required></textarea>
      </label>

      <button type=\"submit\">Post comment</button>
    </form>
  </section>
  "
                     slug)))
              (concat body comments-html))
          body))))


  (defun z/org-html-add-body-classes (output backend info)
    "Add layout-related classes to <body> based on file metadata."
    (when (org-export-derived-backend-p backend 'html)
      (let* ((input-file (plist-get info :input-file))
             (classes
              (delq nil
                    (list
                     (when (and input-file
                                (z/no-sidenotes-file-p input-file))
                       "no-sidenotes")))))
        (if classes
            (replace-regexp-in-string
             "<body\\([^>]*\\)>"
             (format "<body\\1 class=\"%s\">"
                     (string-join classes " "))
             output)
          output))))

  (add-to-list 'org-export-filter-final-output-functions
               #'z/org-html-add-body-classes)
  (add-to-list 'org-export-filter-body-functions
               #'z/org-html-insert-comments-into-body)



  (setq org-html-htmlize-output-type 'css)

  (org-export-define-derived-backend 'z-html 'html
    :filters-alist '((:filter-final-output . z/insert-filetags-after-title)))

  (defun z/org-main-prep (_project)
    (z/generate-recently-updated-org 26))

  (defun z/z-publish-to-html (plist filename pub-dir)
    "Publish FILENAME to HTML using the z-html backend."
    (org-publish-org-to 'z-html filename ".html" plist pub-dir))

  ;; Define the publishing project
  (setq org-publish-project-alist
        `(("org-main"
           :recursive t
           :base-directory "~/master-folder/org-platform/org_web/"
           :publishing-function z/z-publish-to-html
           :publishing-directory "~/master-folder/org-platform/org_web/output"
           :base-extension "org"
  	 :auto-sitemap t
  	 :sitemap-filename "sitemap.org"
  	 :sitemap-title "Sitemap"
  	 :sitemap-sort-files chronologically
           :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :html-head ,z-shared-head
  	 :preparation-function z/org-main-prep
  	 )
  	
  	("org-categories-sitemap"
           :recursive t
           :base-directory "~/master-folder/org-platform/org_web/home"
           :publishing-directory "~/master-folder/org-platform/org_web/output/home"
           :base-extension "org"
  	 :auto-sitemap t
  	 :sitemap-filename "categories.org"
  	 :sitemap-title "Categories"
  	 :sitemap-function z/categories-sitemap
  	 :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :html-head ,z-shared-head
  	 )
          ("org-posts"
           :base-directory "~/master-folder/org-platform/org_web/posts"
           :publishing-directory "~/master-folder/org-platform/org_web/output/posts/"
           :recursive t
           :base-extension "org"
           :publishing-function z/z-publish-to-html
           :with-author nil
           :with-creator nil
           :html-validation-link nil
           :with-toc t
           :section-numbers t
  	 :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :auto-sitemap t
  	 :sitemap-filename "posts-list.org"
  	 :sitemap-title "Posts List"
  	 :sitemap-style list
  	 :sitemap-function z/posts-sitemap
  	 :sitemap-sort-files anti-chronologically
  	 :html-head ,z-shared-head
  	 )
  	("org-blogs"
           :base-directory "~/master-folder/org-platform/org_web/blogs"
           :publishing-directory "~/master-folder/org-platform/org_web/output/blogs/"
           :recursive t
           :base-extension "org"
           :publishing-function z/z-publish-to-html
           :with-author nil
           :with-creator nil
           :html-validation-link nil
           :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :auto-sitemap t
  	 :sitemap-filename "blogs-list.org"
  	 :sitemap-title "Blogs List"
  	 :sitemap-style list
  	 :sitemap-function z/blogs-sitemap
  	 :sitemap-sort-files anti-chronologically
  	 :html-head ,z-shared-head
  	 )
          ("org-2025"
           :base-directory "~/master-folder/org-platform/org_web/blogs/2025/"
           :publishing-directory "~/master-folder/org-platform/org_web/output/blogs/2025/"
           :recursive t
           :base-extension "org"
           :publishing-function z/z-publish-to-html
           :with-author nil
           :with-creator nil
           :html-validation-link nil
           :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :auto-sitemap t
  	 :sitemap-filename "2025-list.org"
  	 :sitemap-title "2025 List"
  	 :sitemap-style list
  	 :sitemap-function z/2025-sitemap
  	 :sitemap-sort-files anti-chronologically
  	 :html-head ,z-shared-head
  	 )
  	("org-career"
           :base-directory "~/master-folder/org-platform/org_web/posts/career/"
           :publishing-directory "~/master-folder/org-platform/org_web/output/posts/career/"
           :recursive t
           :base-extension "org"
           :publishing-function z/z-publish-to-html
           :with-author nil
           :with-creator nil
           :html-validation-link nil
           :html-preamble ,z-preamble
           :html-postamble ,z-postamble
  	 :auto-sitemap t
  	 :sitemap-filename "career-list.org"
  	 :sitemap-title "Career List"
  	 :sitemap-style list
  	 :sitemap-function z/career-sitemap
  	 :sitemap-sort-files anti-chronologically
  	 :html-head ,z-shared-head
  	 )
  	("org-tags"
  	 :base-directory "~/master-folder/org-platform/org_web/tags"
  	 :publishing-directory "~/master-folder/org-platform/org_web/output/tags"
  	 :recursive t
  	 :base-extension "org"
  	 :publishing-function org-html-publish-to-html
  	 :with-author nil
  	 :with-creator nil
  	 :html-preamble ,z-preamble
  	 :html-postamble ,z-postamble
  	 :html-head ,z-shared-head)
  	("org-assets"
           :base-directory "~/master-folder/org-platform/org_web/assets/"
           :base-extension "css\\|js\\|png\\|jpg\\|gif\\|svg\\|pdf\\|woff\\|woff2\\|ttf"
           :publishing-directory "~/master-folder/org-platform/org_web/output/assets/"
           :recursive t
           :publishing-function org-publish-attachment)
  	))


  (delete-directory "~/master-folder/org-platform/org_web/output/" t)
  (delete-directory "~/master-folder/org-platform/org_web/tags/" t)
  (message "Directory deleted")

  (z/write-tag-pages)
  (org-publish-all t)
  (message "Build complete!")
  
  ;;; build-site.el ends here
#+END_SRC

* Publish Script
/Note: This is legacy, just keeping it here for logs/

As the project is hosted on Github, I have created a small script that is able to push changes to the remote repository, which Cloudflare will automatically detect and rebuild the website:

#+BEGIN_SRC bash

  #!/bin/bash

  # Exit immediately if any command fails
  set -e

  # Define paths
  ORG_OUTPUT_DIR="$HOME/master-folder/org-platform/org_web/output"

  cd "$ORG_OUTPUT_DIR"

  echo "HTML published to: $ORG_OUTPUT_DIR"

  # Git commands
  echo "Adding changes to Git..."
  git add .

  echo "Committing..."
  git commit -m "Auto-publish on $(date)" || echo "Nothing to commit."

  echo "Pushing to GitHub..."
  git push origin main

  echo "Done! Changes pushed and Cloudflare should rebuild the site."

#+END_SRC

[fn:1] See: [[../blogs/publish-pages.org][this link]]
