SwanLotus Website

This repository contains the source code and content for the SwanLotus website.

The website uses the Pelican static site generator.

Getting Started

Before setting up your development environment please ensure that you have the latest version of Python installed on your machine.

Then follow the steps below to set up your development environment:

1. Install Sass, Git, Pandoc, pipenv and pyenv.

   sudo pacman -Syyu
   sudo pacman -S dart-sass git pandoc python-pipenv pyenv

2. Clone the swanlotus repository:

   git clone https://github.com/kleinbottle/swanlotus <directory-name>

   You will be asked to enter your username and password to clone the repository.

3. Change into the directory you have cloned swanlotus into:

   cd <directory-name>

4. Save your username and password in the git credential store and update your repository:

   git config credential.helper store
   git pull --rebase

   You will be asked for your username and password again but they will be saved in the file ~/.git-credentials for future use.

5. Set the commit username, email address and rebase option globally. To set them for just this repository remove --global option in the commands below:

   git config --global user.name "<github-username>"
   git config --global user.email "<github-email-address>"
   git config --global pull.rebase true

6. Set up the default editor for amending commits. Again remove --global to just set it for this repository:

   git config --global core.editor "<editor>"

7. Create a Python 3 development environment for Pelican and associated dependencies:

   pipenv install --dev

   You may be asked to install version 3.13.0 of Python by pyenv, answer with y at the prompt to install it.

   If we update the version of Python we would have to update the versions in the following files:

   • .python-version
   • Pipfile
   • netlify.toml

   Then we would then need to destroy the existing virtual environment and recreate it:

   pipenv --rm
   pipenv install --dev

   Again you may be asked to install a version of Python, answer with y at the prompt.

Updating your local repository

To update your local repository with changes from the remote repository execute:

make pullSL

Viewing the Site

To generate all HTML content and start the development server execute:

make devserver

You can then navigate to localhost to view the site.

Creating Blogs

To create a new blog entry follow the steps below:

1. Create a new directory matching the title of your blog under the content/blogs directory.

2. Create a file called <blog-title>.md under the content/blogs/<blog-title> directory and add your content in Pandoc's flavor of Markdown.

3. If you have citations for the blog create a <blog-title>.bib file under the content/blogs/<blog-title> directory and add your citations.

4. If you have static content like images create a directory called images in the content/blogs/<blog-title> directory and place your images in that directory.

5. To attach to static content to your blog use the {attach}images/<image-name>.<image-extension> syntax.

6. Convert the blog to HTML locally by executing the following commands:

   make clean
   make devserver

7. Now you may view the blog on localhost.

8. Once you are finished with your blog and are happy with the end result, you may commit to GitHub by executing the following commands:

   make pushSL COMMIT_MSG="<commit-message>"

   Once you have pushed the changes Netlify will build the site automatically and the new content will be available on the site.

Writing only selected blogs

If you are working on a single blog you may want to just generate that blog instead of the whole site to save time.

To do so, set the ARTICLE_PATHS = ["blogs/"] to ARTICLE_PATHS = ["blogs/<blog-directory>"] in pelicanconf.py. This way only the blog in that specific directory will be generated.

Creating Pages

To create a static page like the Home page follow the steps below:

1. Create a new page <page-title>.md in the content/pages directory.

2. Add your content to <page-title>.md.

3. If you wish to add your new page to the menu bar on the site you would need to add a new entry under MENUITEMS setting in the pelicanconf.py file as shown below:

   MENUITEMS = (
       ...
       ("<page-title>", "<page-title>.html"),  # New entry added to the end of the tuple
   )

   If you wish to add submenus you may specify them as:

   MENUITEMS = (
       ...
       ...
       ("<menu-item>", [
           ("<submenu-item-one>", "<item-one.html>"),
           ("<submenu-item-two>", "<item-two.html>"),
       ]),
       ...
       ...

   Note: The pages on the menu will follow the order of the menu items shown above.

4. Convert the page to HTML locally by executing the following commands:

   make clean
   make devserver

5. Now you may view the page on localhost.

6. Once you are finished with your page and are happy with the end result, you may commit to GitHub by executing the following commands:

   make pushSL COMMIT_MSG="<commit-message>"

   Once you have pushed the changes Netlify will build the site automatically and the new content will be available on the site.

CSS Stylesheets

The main CSS stylesheet swanlotus.css is generated through SASS and uses the Bulma CSS framework.

The main stylesheet imports three other stylesheets:

• citations.scss - CSS stylesheet for citations generated by pandoc-crossref filter in standalone mode.
• fonts-and-alignment.sass - SASS file corresponding to LaTeX commands for fonts and alignment adapted from the fonts-and-alignment Lua filter SASS specimen.
• modal.scss - CSS stylesheet Provides Modal boxes for images through the addition of the modal-target class adapted from the Simple image modal Codepen example.
• zenburn-highlighting.scss - CSS stylesheet for Zenburn code highlighting generated using the command pandoc --highlight-style=zenburn --template=highlighting-css.template sample.md -o zenburn-highlighting.css.

To generate the final stylesheet swanlotus.css execute:

make css

The stylesheet will now be available in the theme/swanlotus/static/css directory.

JavaScript

The site also uses some JavaScript to enhance the behaviour of the site as explained below:

• modal.js - Used by the modal boxes for the enlargment of the images whe clicked. The code for this is adapted from the Simple image modal Codepen example.
• responsive_menu.js - Used to reduce and expand navigation bar as needed to support multiple screen sizes. The code for this is adapated from the Bulma Documentation.
• table_of_contents.js - Expands and collapses the table of contents of blogs as needed to support muliple screen sizes.
• mathjax-config.js - Used to load configuration options for MathJax.

MathJax

As several blogs on this site are mathematical in nature the MathJax display engine is used to render mathematical equations and expressions.

MathJax has been configured to use the STIX2 fonts for mathematical expressions.

In addition, all mathematial expressions are scaled to 91% of the original size to match the size of the surrounding text.

These configuration options are set in the /theme/swanlotus/static/js/mathjax-config.js file. You may modify these settings as needed.

Please note that the site is using a Beta release of MathJax as the current stable release, 3.2.2 does not have font selection capabilities. For more information on font selection please see these release notes.

Once a new stable release of MathJax is available the site will be updated.

Images

Modals for Images

To add a Modal box for any image on the website just add the class modal-target to the image. This can be done in Pandoc as follows:

![<image-caption>]({attach}images/<image-name>.jpg){.modal-target}

Please note that the Modal box will noot display the caption only and enlarged version of the image.

Open Graph Images

If you wish to add an Open Graph image to a page or a blog you may do so by adding the following field in the front matter of your blog or page:

opengraphimage: "<image-name>.jpg"

Both JPG and PNG images are supported by the Open Graph protocol.

Typically, it takes 24 hours for an Open Graph image to appear in WhatsApp. In Telegram access the Webpage Bot and input the webpage link to update the link preview to have it appear immediately.

Netlify Deployment

Netlify currently uses the Ubuntu 20.04 LTS Focal Fossa image to build this site.

Since the default version of Python is ancient on the above image we use a netlify.toml file to instruct Netlify to use a more up-to-date version by setting the PYTHON_VERSION environment variable.

We always want to use the latest version of Pandoc and pandoc-crossref to avail of new features. Since the above image does not always have the most recent versions or may not contain the package at all, the Netlify community suggested to make use of HomeBrew.

By specifying the packages in a Brewfile.netlify we instruct the builder to download the latest version of these packages from Homebrew and install them on the image.

This feature is in early Alpha and may change significantly in the future.

Please see the Netlify documentation for a list of available packages.

To build the site on Netlify use the following Pelican command:

pelican content -s publishconf.py

The publishconf.py file contains settings that are specific to the live site and overrides the settings in pelicanconf.py.

Do not update publishconf.py unless you need to change settings on the live site.