site: Vendor MathJax from guix, removing dependency on CDN

* .gitignore: Ignore lib/MathJax symlink. * README.org: Variety of changes, most notably using the README.org file as a literate source file, which generates various development scripts and a Makefile. One such script is the vendoring script, which is used to setup vendor symlinks. * bootstrap.sh: Run emacs to tangle the literate README.org file, after which, run setup vendored dependency links. * guix.scm: Depend on js-mathjax, and vendor its built files into lib/MathJax before building the site. * pages/index.markdown: Remove stale reference to jquery-address. * src/site.hs: Adjust hakyll rules to include MathJax from its now locally vendored location. Additionally, do a tiny bit of rule tidying. * templates/default.html: Remove stale reference to appcache. Remove reference to MathJax via cdn and reference the now vendored variant.
2023-12-26 18:01:14 -05:00 · 2023-12-26 18:01:14 -05:00 · e4032ba6b3
parent bad2d07ce9
commit e4032ba6b3
7 changed files with 95 additions and 78 deletions
--- a/.gitignore
+++ b/.gitignore
@ -18,6 +18,9 @@ infra/terraform.tfstate.d
 infra/*.local.tfvars
 infra/*.plan

+# Vendored libraries
+lib/MathJax
+
 # Generated by ./bootstrap
 Makefile
 scripts
--- a/README.org
+++ b/README.org
@ -26,7 +26,7 @@ libraries:
 - [[http://fvisser.nl/clay/][Clay]] is used for CSS pre-processing
 - [[http://www.getskeleton.com/][Skeleton]] is used for CSS boilerplate
 - [[http://www.mathjax.org/][MathJax]] is used for rendering mathematics
- [[http://jquery.com][JQuery]] and [[https://github.com/asual/jquery-address][JQuery-address]] are used for various DOM manipulations
+- [[http://jquery.com][JQuery]] is used for various DOM manipulations
 - [[https://guix.gnu.org/][Gnu Guix]] is used to manage development environments and packaging
 - [[http://inkscape.org/][Inkscape]] and the [[http://www.gimp.org/][Gimp]] were used to create various images/artwork
 - [[http://www.gnu.org/software/freefont/][Gnu Free Fonts]], specifically *FreeMono* is used as main font
@ -45,64 +45,42 @@ Various licenses ([[https://www.gnu.org/licenses/gpl.html][GPLv3]], [[http://cre
 License]]) are deployed dependent on which part of the site is in question. Please see the
 [[./LICENSE][LICENSE]] file for full details.

-* TODO Repository Structure
+* Repository Structure

-#+begin_src text
-  .
-  ├── blog-rekahsoft-ca.cabal
-  ├── bootstrap.sh
-  ├── channels.scm --
-  ├── clay
-  │  └── *.hs -- clay source files
-  ├── css
-  ├── drafts
-  │  └── *.md -- draft posts
-  ├── files
-  │  ├── images
-  │  └── source
-  ├── fonts
-  │  └── *.{ttf,woff,...} -- font files
-  ├── guix.scm
-  ├── images
-  │  └── ...
-  ├── images-src
-  │  └── ...
-  ├── infra
-  │  ├── channels.scm -> ../channels.scm
-  │  ├── main.tf
-  │  ├── Makefile
-  │  ├── manifest.scm
-  │  ├── outputs.tf
-  │  ├── production.tfvars
-  │  ├── staging.tfvars
-  │  └── variables.tf
-  ├── js
-  │  └── *.js -- javascript files
-  ├── lib
-  │  └── ... -- javascript libraries
-  ├── LICENSE
-  ├── manifest.scm
-  ├── pages
-  │  └── ...
-  ├── posts
-  │  └── ...
-  ├── README.org
-  ├── robots.txt
-  ├── Setup.hs
-  ├── site
-  ├── src
-  │  └── site.hs
-  └── templates
-     ├── default.html
-     ├── pages
-     ├── partials
-     └── tag-page.html
-#+end_src
+- ~blog-rekahsoft-ca.cabal~   :: Cabal package definition.
+- ~bootstrap.sh~              :: Generate development scripts, Makefile, and setup vendor links based on this literate configurationl
+- ~channels.scm~              :: Guix Channel File.
+- ~clay/*.hs~                 :: Clay source files.
+- ~css/*.css~                 :: CSS source files (will be minified).
+- ~drafts/*.md~               :: Draft posts.
+- ~files/images/~             :: Folder for images used in posts.
+- ~files/source/~             :: Folder for source code used in blog posts/pages.
+- ~fonts/*.{ttf,woff,...}~    :: Font files
+- ~guix.scm~                  :: Guix package definition for this site-builder and its resulting site.
+- ~images/*~                  :: Folder for images used on pages or in templates.
+- ~images-src/*~              :: Folder for the image source files (should be 1-to-1 with files in ~images/*~).
+- ~infra/~                    :: Infrastructure folder; contains terraform based Infrastructure As Code (IAC).
+- ~infra/channels.scm~        :: Symlink to ~../channels.scm~ (can be independent if needed).
+- ~infra/*.tf~                :: Terraform source files.
+- ~infra/*.tfvars~            :: Terraform variables files for each environment (non-secrets).
+- ~infra/Makefile~            :: Makefile used for terraform deployments.
+- ~infra/manifest.scm~        :: Guix manifest that defines the necessary deployment environment.
+- ~js/*.js~                   :: Javascript files.
+- ~lib/*~                     :: Javascript libraries.
+- ~LICENSE~                   :: License file.
+- ~pages/*.markdown~          :: Page content.
+- ~posts/*.markdown~          :: Blog posts.
+- ~README.org~                :: Org-mode documentation.
+- ~robots.txt~                :: Robot Exclusion Protocol file.
+- ~Setup.hs~                  :: Cabal build script for this site.
+- ~src/*.hs~                  :: Hakyll powered site builder.
+- ~templates/~                :: Folder for all template files.
+- ~templates/default.html~    :: Entry point template (defines html document used for all pages).
+- ~templates/pages/*.html~    :: Html page templates (correspond 1-to-1 with pages/*.markdown files).
+- ~templates/partials/*.html~ :: Partial template files, for use within templates.
+- ~templates/tag-page.html~   :: Template for creating pages about tags with a specific tag.

-* TODO Guix Development Environment
-:PROPERTIES:
-:header-args:  :session *vterm blog-rekahsoft-ca* :results none
-:END:
+* Guix Development Environment

 [[https://guix.gnu.org/][Gnu Guix]] is used to package this project and manage its dependencies, as well as to provide
 reproducible development environments.
@ -131,7 +109,7 @@ Then run the development 'auto-watching' environment:

 This starts a containerized local development environment that uses [[https://github.com/ndmitchell/ghcid/][ghcid]] to watch haskell
 sources and restart hakyll's [[*Watch][site watch]] feature when changes occur. The site will be
-available at http://localhost:3000, and will be automatically rebuild as site files change
+available at http://localhost:3000, and will automatically rebuild as site files change
 (templates, post, pages, etc..).

 ** Start Development Environment
@ -144,7 +122,7 @@ The development environment is defined by the following files:
 To start a development environment, run the following:

 #+begin_src sh :mkdirp yes :tangle ./scripts/start-development-environment.sh :tangle-mode (identity #o555)
-  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -f guix.scm -Df guix.scm
+  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -f guix.scm -Df guix.scm $@
 #+end_src

 This uses the [[info:guix#Invoking guix time-machine][guix time-machine]] feature to ensure the development environment is reproducible
@ -169,7 +147,7 @@ or needed, as the deployment environment is used solely for its side effects.
  top-level of the repository, however this would complicate [[*Composing Site Development and Deployment Environments][Composing Site Development and
  Deployment Environments]], so its preferred that all guix environments for the project,
  including the development and deployment environment use the same set of Guix channels.
- [[./infra/manifest.scm][infra/manifest.scm]] :: Defines packages required for deployment of this site
+- [[./infra/manifest.scm][infra/manifest.scm]] :: Defines packages required for deployment of this site.

 To start a deployment environment, run the following:

@ -181,7 +159,7 @@ To start a deployment environment, run the following:
 *** Composing Site Development and Deployment Environments

 #+begin_src sh :mkdirp yes :tangle ./scripts/start-development-and-deployment-environment.sh :tangle-mode (identity #o555)
-  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^AWS.*$' -f guix.scm -Df guix.scm -m infra/manifest.scm
+  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^AWS.*$' -f guix.scm -Df guix.scm -m infra/manifest.scm $@
 #+end_src

 ** Hakyll Site Commands
@ -235,8 +213,9 @@ provided by Hakyll.
 When making adjustments to the site builder itself, it is useful to have functionality
 similar to the site content watching feature of Hakyll, but for haskell source files.
 Luckily, [[https://github.com/ndmitchell/ghcid/][ghcid]] can be used for this, and is included in the projects development
-~manifest.scm~ file.
+dependencies, specified in the ~guix.scm~ file.

+#+name: watch-all
 #+begin_src sh :mkdirp yes :tangle ./scripts/watch-all.sh :tangle-mode (identity #o555)
  ghcid --test _devWatch
 #+end_src
@ -322,13 +301,26 @@ content development, this is not a concern.
  guix time-machine -C channels.scm -- shell -CN -E LANG -E TERM -f guix.scm
 #+end_src

-* TODO Makefile
+* DOING Vendor external libraries using Guix
+
+Some ...
+
+#+begin_src sh :mkdirp yes :tangle ./scripts/vendor-deps.sh :tangle-mode (identity #o555)
+  [ -h lib/MathJax ] && rm lib/MathJax
+  [ -e lib/MathJax ] && echo "lib/MathJax exists, but not as a symlink; please manually remove it!" && exit 1
+  ln -s $(guix time-machine -C channels.scm -- shell -Df guix.scm -- bash -c 'echo $GUIX_ENVIRONMENT')/share/javascript/mathjax lib/MathJax
+#+end_src
+
+* Makefile
+
+In order to simplify running the various commands outlined throughout this document, a
+~Makefile~ is defined below.

 #+begin_src makefile :noweb yes :tangle Makefile :tangle-mode (identity #o444)
 # THIS IS A GENERATED FILE, DO NOT EDIT!
 # Instead modify README.org appropriately

-.DEFAULT_GOAL := watch-all
+.DEFAULT_GOAL := watch

 .PHONY: bootstrap
 bootstrap:
@ -350,13 +342,22 @@ dev-all:
 watch-all:
 	./scripts/watch-all.sh

+.PHONY: watch
+watch:
+	./scripts/start-development-environment.sh -- <<watch-all>>
+
 .PHONY: build
 build-release:
 	./scripts/build-release.sh

+.PHONY: vendor
+vendor:
+	./scripts/vendor-deps.sh
+
 .PHONY: clean
 clean:
 	./scripts/clean-guix-store.sh
+	rm -rf scripts lib/MathJax Makefile
 #+end_src

 * Continuous Integration & Delivery
@ -376,5 +377,4 @@ with docker as follows, where ~<version>~ is the drone-cli version.

 * Known Issues

-If you have an issue while browsing [[http://www.blog.rekahsoft.ca][my blog]] please file a issue in the [[https://git.rekahsoft.ca/rekahsoft/blog-rekahsoft-ca/issues][blog-rekahsoft-ca]]
-issue tracker.
+If you have an issue while browsing [[http://www.blog.rekahsoft.ca][my blog]] please let me know via [[https://www.blog.rekahsoft.ca/contact.html][email]].
--- a/bootstrap.sh
+++ b/bootstrap.sh
@ -1,3 +1,5 @@
 #!/usr/bin/env bash

 guix time-machine -C channels.scm -- shell -C emacs git -- emacs -q README.org --batch --eval '(org-babel-tangle)'
+
+./scripts/vendor-deps.sh
--- a/guix.scm
+++ b/guix.scm
@ -24,6 +24,7 @@
 (guix git-download)
 (guix gexp)
 (gnu packages base)
+ (gnu packages javascript)
 (gnu packages haskell-apps)
 (rekahsoft-gnu packages haskell-web)
 (git))
@ -47,7 +48,8 @@
                       ("make" ,gnu-make)
                       ("ghcid" ,ghcid)))
      (inputs `(("ghc-hakyll" ,ghc-hakyll)
-                ("ghc-clay" ,ghc-clay)))
+                ("ghc-clay" ,ghc-clay)
+                ("js-mathjax" ,js-mathjax)))
      (outputs '("out" "site" "static"))
      (arguments
       `(#:phases
@ -62,6 +64,11 @@
             (lambda* (#:key outputs #:allow-other-keys)
               (let* ((out (assoc-ref outputs "out"))
                      (site (assoc-ref outputs "site")))
+                 ;; Copy (vendor) dependencies: MathJax
+                 (copy-recursively (string-append (assoc-ref %build-inputs "js-mathjax")
+                                                  "/share/javascript/mathjax")
+                                   "lib/MathJax" #:follow-symlinks? #t)
+
                 ;; All source files are read-only and need to be adjusted to allow the
                 ;; site to be generated at the end of the build
                 (for-each make-file-writable (find-files "."))
--- a/pages/index.markdown
+++ b/pages/index.markdown
@ -15,7 +15,6 @@ This website was proudly made with open source software! Specifically:
 - [Clay][]
 - [Skeleton][]
 - [JQuery][]
- [JQuery-address][]
 - [MathJax][]
 - [Inkscape][]
 - [Gimp][]
--- a/src/site.hs
+++ b/src/site.hs
@ -92,10 +92,21 @@ myConfig = defaultConfiguration

 siteRules :: Rules ()
 siteRules = do
-  match ("action/**" .||. "files/**" .||. "images/**" .||. "fonts/**" .||. "robots.txt") $ do
+  match ("js/**"
+         .||. "files/**"
+         .||. "images/**"
+         .||. "fonts/**"
+         .||. "robots.txt") $ do
    route   idRoute
    compile copyFileCompiler

+  forM_ [("lib/MathJax/fonts/HTML-CSS/**", gsubRoute "lib/MathJax/" $ const ""),
+         ("lib/MathJax/**" .&&. complement "lib/MathJax/fonts", gsubRoute "lib/" $ const ""),
+         ("lib/JQuery/*", gsubRoute "JQuery" $ const "js")] $ \(p, r) ->
+    match p $ do
+        route   r
+        compile $ copyFileCompiler
+
  match "css/**" $ do
    route   idRoute
    compile compressCssCompiler
@ -227,19 +238,13 @@ siteRules = do
                     >>= fmap (take 10) . recentFirst
      renderAtom (feedConfiguration Nothing) feedCtx blogPosts

-  forM_ [("js/**", idRoute),
-         ("lib/JQuery/*", gsubRoute "JQuery" $ const "js")] $ \(p, r) ->
-    match p $ do
-        route   r
-        compile $ copyFileCompiler
-
 _devWatch :: IO ()
 _devWatch = do
  _ <- hakyllWithExitCodeAndArgs myConfig (Options { verbosity = False, optCommand = Rebuild }) $ siteRules
  hakyllWithArgs myConfig (Options { verbosity = False, optCommand = Watch "localhost" 3000 False }) $ siteRules

 main :: IO ()
-main = hakyllWith myConfig $ siteRules
+main = hakyllWith myConfig siteRules

 ---------------------------------------------------------------------------------------------------------
 -- Functions & Constants --------------------------------------------------------------------------------
--- a/templates/default.html
+++ b/templates/default.html
@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html class="en" $if(appcache)$manifest="/manifest.appcache"$endif$>
+<html class="en">
  <head>
    <!-- Basic Page Needs -->
    <meta charset="utf-8">
@ -50,7 +50,8 @@

    <!-- External javascript libraries: JQuery, MathJax -->
    <script src="/lib/js/jquery-1.12.3.js" type="text/javascript"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML" type="text/javascript"></script>
+    <script src="/MathJax/MathJax.js" type="text/javascript"></script>
+    <script src="/MathJax/config/TeX-MML-AM_CHTML.js" type="text/javascript"></script>

    <!-- Custom javascript for user interactivity -->
    <script src="/js/default.js" type="text/javascript"></script>