Merge pull request #214 from Interlisp/staging

Rework hugo.toml file.

Author: stumbo

.github/workflows/gh-pages.yml

@@ -28,6 +28,11 @@ on:
   schedule:
     - cron: "0 3 * * *"
 
+env:
+  # ----------------------------------------------------------------------------
+  # Specify the deployment environment:  staging or production
+  hugoEnvironment: production
+
 jobs:
   # ----------------------------------------------------------------------------
   # Use the Zotero REST API to get the current version of the Zotero Bibliography
@@ -102,7 +107,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v3
         with:
-          hugo-version: '0.122.0'
+          hugo-version: '0.127.0'
           extended: true
 
       - name: Setup Node
@@ -115,7 +120,7 @@ jobs:
       - run: npm install --verbose
 
       - name: Build
-        run: hugo
+        run: hugo -e $hugoEnvironment
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4

README.md

@@ -147,12 +147,12 @@ hugo version
 The response will be something along the lines of:
 
 ```bash
-hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended linux/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
+hugo v0.126.1-3d40aba512931031921463dafc172c0d124437b8+extended linux/amd64 BuildDate=2024-05-15T10:42:34Z VendorInfo=gohugoio
 ```
 
-Be sure your version is at least `v0.101.0`. Older versions of `hugo` may fail to load correctly.
+Be sure your version is at least `v0.122.0`. Older versions of `hugo` may fail to load correctly.
 
-Secondly, there is one data file that is required to successfully build and run the `Interlisp.org` website locally, `data/bibliography.json`.
+Secondly, there is one data file that is required to successfully build and run the `Interlisp.org` website locally, `static/data/bibliography.json`.
 The production version of the website uses a GitHub Action to retrieve this file.
 We can mimic that functionality by going to the `scripts` directory in your clone of the `Intelisp.github.io` repository.
 Once in the directory, run the following command:
@@ -162,68 +162,74 @@ Once in the directory, run the following command:
 ```
 
 This script will retrieve the bibliography from our Zotero library, format it appropriately and place the created file
-in the appropriate location, the `data` directory.
+in the appropriate location, the `static/data` directory.
 
 This completes all the setup required for `Hugo`.
 
 To run `Hugo` go to the root directory of your repository clone and run the following command:
 
 ```bash
-hugo server
+hugo server --logLevel debug -v --renderToMemory -e development
 ```
 
 `Hugo` will start and automatically download the Docsy theme and its dependencies as hugo modules.  You should see output along the lines of:
 
 ```bash
-hugo: downloading modules …
-hugo: collected modules in 17781 ms
+Watching for changes in /home/wstumbo/development/stumbo.github.io/{archetypes,content,layouts,package.json,static}
+Watching for config changes in /home/wstumbo/development/stumbo.github.io/config/_default, /home/wstumbo/development/stumbo.github.io/config/development, /home/wstumbo/development/stumbo.github.io/go.mod
 Start building sites …
-hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended linux/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio
+hugo v0.126.1-3d40aba512931031921463dafc172c0d124437b8+extended linux/amd64 BuildDate=2024-05-15T10:42:34Z VendorInfo=gohugoio
+
 
                    | EN
 -------------------+-----
-  Pages            | 61
+  Pages            | 52
   Paginator pages  |  0
-  Non-page files   | 13
-  Static files     | 68
-  Processed images | 46
-  Aliases          |  4
-  Sitemaps         |  1
+  Non-page files   | 46
+  Static files     | 97
+  Processed images | 47
+  Aliases          | 66
   Cleaned          |  0
 
-Built in 1349 ms
-Watching for changes in /home/wstumbo/development/Interlisp.github.io/{archetypes,assets,content,data,layouts,package.json,static,themes}
-Watching for config changes in /home/wstumbo/development/Interlisp.github.io/config.toml, /home/wstumbo/development/Interlisp.github.io/go.mod
+Built in 3230 ms
 Environment: "development"
 Serving pages from memory
 Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
-Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
+Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
 Press Ctrl+C to stop
 ```
 
 `Hugo` is now running.  You can go to [http://localhost:1313](http://localhost:1313) to review the locally running version of the website.  
 For most changes you should be able to review the text and layout to validate the effects are as expected.
 
+You can get additional debugging information by adding the following two options
+to your `hugo` command `--logLevel debug -v`.  
+
 Once you have validated your changes, create a pull request to merge your changes into the `main` branch.
 
 ## Layout of the `Interlisp.github.io` repository
 
 The layout of the `Interlisp.github.io` repository follows the standard [`Hugo` directory structure](https://gohugo.io/getting-started/directory-structure/).  Directories
 that have components specific to `Interlisp.github.io` are as follows:
 
-- `.` - at the root, `config.toml` file provides the general site configuration information
 - `.github\workflows`  - home to the github actions `gh-pages.yml` that specifies how to build and release the Interlisp home page
 - `assets` - customization of the `Docsy` theme for Interlisp.
   - `icons` - holds and `svg` version of `Interlisp-D' logo.  This logo is used in the page header
   - `scss` - contains some custom `scss`
     - `_styles_project.scss` sets the size of the `svg` file in the header and disables the edit page functionality
     - `main.scss` - links in the `scss` updates
+- `config` - contains all the site specific configuration information
+  - `_default` - configuration information shared across different supported environments [development, staging, production]
+  - `development` - configuration information specific to the development environment
+  - `production` - configuration information specific to the production environment
+  - `staging` - configuration information specific to the staging environment
 - `content\en` - home of all the content for the web page.  We currently only support the English language.  `Hugo` supports multiple languages and we have not disabled that feature. However there are no plans at present to transcribe the web pages and documentation into another language.
-- `data`  - holds `bibliography.json` used to create the [bibliography table](https://interlisp.org/bibliography/)
 - `layout`
   - `shortcodes` - a simple snippet inside a content file that Hugo will render using a predefined template
     - `bibTable.html` - a shortcode used to format the [bibliography table](https://interlisp.org/bibliography/)
-- `static` - the data in this folder is copied directly into the folder structure of the home page  
+- `static` - the data in this folder is copied directly into the folder structure of the home page 
+  - `css` - custom css files 
+  - `data`  - holds `bibliography.json` used to create the [bibliography table](https://interlisp.org/bibliography/)
   - `documentation` - contains the pdf files referenced in the document section of the home page
   - `favicons` - contains `favicon.png` a small icon that browsers can use when referencing the website
   - `Resources` - contains the current `Interlisp-D` logo, used on the home page, and another instance of `favicon.png`
@@ -236,11 +242,12 @@ the `Interlisp.org` website, our GitHub sites used for continued development of
 Medley Interlisp, and the discussions groups associated with both the Medley project and
 Interlisp.
 
-The search engine is identified in the `hugo.toml` file:
+The search engine is identified in the `config/params.yaml` file:
 
-```toml
-# Google Custom Search Engine ID. Remove or comment out to disable search.
-gcs_engine_id = "33ef4cbe0703b4f3a"
+```yaml
+# Google custom seach engine configuration
+#  gcs_engine_id:  search engine 
+gcs_engine_id: 33ef4cbe0703b4f3ax
 ```
 
 Search results are returned and presented using the page template, `search.md`.

config/_default/hugo.yaml

@@ -0,0 +1,52 @@
+# *******************************************************************
+#
+# Hugo parameters for Interlisp.org
+#
+# An overview of hugo configuration files can be found at:
+#  https://gohugo.io/getting-started/configuration/#configure-server
+#
+
+# relativeURLs: Enable to force all relative URLs to be relative to content root
+relativeURLs: false
+
+# canonifyURLs: Convert relative URLs to absolute URLs
+canonifyURLs: false
+
+# enableRobotsTXT:  Enable generation of robots.txt file.  When enabled this
+# will overwrite the default robots.txt file that disallows crawling.
+# Default to false and set to true for production in config/production/hugo.yaml
+enableRobotsTXT: false
+
+# aasetDir:  Location where Hugo looks for assets
+assetDir: static
+
+# Enable .GitInfo object for each page.  This will give values to .Lastmod etc.
+enableGitInfo: false
+
+# Top Level Language defaults 
+#  See languages.yaml for language specific values
+defaultContentLanguage: "en"
+defaultContentLanguageInSubdir: false
+
+# Useful when translating.
+enableMissingTranslationPlaceholders: true
+
+# Disable rendering of the specified page kinds 
+disableKinds: 
+ - taxonomy
+ - term
+ - RSS
+
+# Code Highlighting configuration 
+#  Not Used.  Code highlighting is controlled using the highlighting
+#  section in `markup.yaml`
+#pygmentsCodeFences: false
+#pygmentsUseClasses: false
+# Use the new Chroma Go highlighter in Hugo.
+# pygmentsUseClassic: false
+# pygmentsOptions: linenos=table
+# See https://help.farbox.com/pygments.html
+
+# Comment out if you don't want the "print entire section" link enabled.
+# [outputs]
+# section = ["HTML", "print"]

config/_default/imaging.yaml

@@ -0,0 +1,9 @@
+# ****************************************************************************
+#
+# Image processing setup 
+#
+# Configuration information available at:
+# https://gohugo.io/content-management/image-processing/#resampling-filter
+resampleFilter: CatmullRom
+quality: 75
+anchor: smart

config/_default/languages.yaml

@@ -0,0 +1,13 @@
+# ****************************************************************************
+#
+# Language configuration
+#
+# See:  https://gohugo.io/content-management/multilingual/
+#
+en:
+  languageName: English"
+  # Weight used for sorting.
+  weight: 1
+  contentDir: content/en
+  params:
+    description: "Dedicated to restoring and preserving the Interlisp experience"

config/_default/markup.yaml

@@ -0,0 +1,29 @@
+# ****************************************************************************
+#
+# Goldmark markdown processor setup 
+#
+# See: https://gohugo.io/getting-started/configuration-markup/#goldmark
+#      for additional configuration options
+#
+goldmark:
+  renderer:
+    unsafe: true
+#
+# Code block processing
+#
+# See:  https://gohugo.io/getting-started/configuration-markup/#highlight
+#       for additional information on configuration options.
+#   https://www.docsy.dev/docs/adding-content/lookandfeel/#code-highlighting-with-chroma
+#       contains Docsy specfiic code highlighting information    
+highlight:
+  # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
+  #style: solarized-dark
+  style: tango
+  codeFences: true
+  noClasses: true
+  hl_inline: false
+  # Uncomment if you want your chosen highlight style used for code blocks without a specified language
+  guessSyntax: true
+  tabWidth: 4
+  #lineNoStart: 1
+  lineNos: false

config/_default/menu.yaml

@@ -0,0 +1,25 @@
+# ****************************************************************************
+#
+# Hugo - Top-level navigation (horizontal)
+#
+main:
+  - name: GitHub
+    weight:  -10
+    pre: <i class='fab fa-github'></i>
+    url: https://github.com/interlisp
+  - name: Get Involved
+    weight: -30
+    pre: <i class='fas fa-handshake-simple'></i>
+    url: /getInvolved/
+  - name: Software
+    weight: -50
+    pre: <i class='fas fa-cube'></i>
+    url: /software/
+  - name: Project
+    weight: -70
+    pre: <i class='fas fa-globe'></i>
+    url: /project/
+  - name: History
+    weight: -90
+    pre: "<i class='fas fa-book'></i>"
+    url: /history/ 

config/_default/module.yaml

@@ -0,0 +1,11 @@
+  proxy: "direct"
+  # uncomment line below for temporary local development of module
+  # replacements = "github.com/google/docsy -> ../../docsy"
+  hugoVersion:
+    extended: true
+    min: "0.73.0"
+  imports:
+    - path: "github.com/google/docsy"
+      disable: false
+    - path: "github.com/google/docsy/dependencies"
+      disable: false