Site content and tooling for maintaining the uPortal static website.
There are two workflows that can be used when managing content for the uPortal website.
The easiest workflow is when you just want to create or update content. Only Git is required
to commit changes to the repo and push them up to GitHub. Markdown is and HTML are broadly known,
so updating this content is simple and rarely requires site testing.
Another workflow is where you want to run a web server to confirm your changes. This workflow
requires installation of Java and Clojure to run the tooling. This approach allows you to display
the site in a browser as it will appear live. As you change content, a page refresh in your browser
will show your changes.
There is a third workflow very similar to the previous one for enhancements to the tooling. Again,
Java and Clojure are required and changes can be seen after a source file save and browser
page refresh. The only notable difference from the other workflow is that new dependencies will
require restarting the web server.
Installation of Git is the most basic command needed. Your computer should already have it installed. If not, check your package manager or download from the official site. Below are some common ways
to install Git in case you are not a developer. However, there are many other ways to install Git.
See the Official Git Installing Page
$ brew install git
- Download the latest Git for Windows installer
- Run the installer and follow the prompts.
$ sudo apt-get update$ sudo apt-get install git-all
$ sudo dnf install git-all
Git is the only tool you need for the basic editing workflow.
Java is required for running the web server, and generating the static distribution.
The version should be 8+.
While there are official downloads of Java from Oracle many of the uPortal developers perfer to use SDKMAN! as it supports many different versions of Java from a variety of vendors.
Clojure, also, is required for running the web server, and generating the static distribution.
Actually, it is a language that sits on the Java JVM which is why Java is required.
Clojure packages now include both the language and a development environment with tools. Installation instructions can be found on the Official Install Clojure page.
If you are focusing on content (as opposed to working on the code), you will only need to look at
the resources/ directory. There are currently three directories: md/, partials/, and public/.
Each directory is processed differently.
The md/ Markdown directory hosts the Markdown files for the website. This files will have the
layout applied and be converted to HTML. Subdirectories for the path for the URL. For example,
if you have the following resources/md/contact/us.md then the site will display that content
at /contact/us.html.
We expect most of the content will be Markdown.
The partials/ directory is where HTML fragments in files live. The expectation is that the content
will be a <div> or other HTML markup that can be placed in a <div> of the layout. There should
not be any <head> or <body> tags in these files. They will have the layout applied to them,
and they will display at a URL like Markdown files. A partial in the repo at resources/partials/contact/us.html will be displayed at /contact/us.html.
The public/ directory will have minimal processing. The expectation is that the files here will
not have the layout applied. HTML files here will be used mostly as is. There might be some light
processing, like code styling applied, but it will be kept to a minimum. CSS and JavaScript files
should reside here. Again, the directories form the basis of URL paths. An HTML file at resources/public/contact/us.html will display at /contact/us.html.
You may have noticed that there is a potential for different files to end up at the same URL. This is not good! So one of the tests will detect when files from different sections will collide on the same URL.
If you are more inclined to see your changes before committing them to the repo, you will want to
run the web server to see your changes live. Java and Clojure will need to be installed.
You will also need to have a clone of this repo on your local drive.
-
From a command line / shell, navigate to this repo on your drive.
$ cd <repo_directory>
-
Start the web server and wait 30 seconds for it to start.
$ clj -M:run
-
Point your browser at
http://localhost:8090/to see the landing page. -
Edit or add a page as above.
-
Navigate to the page and refresh as you save your changes.
-
To stop the web server, use Ctrl+C in the command line / shell.
You can also specify the port, mode (dev|prod), and context-path for assets.
$clj -M:run 8090 prod /uPortal-website
If you want to specify a mode, you have to include the port.
Generating the static files and directories to deploy is a simple command with one optional parameter: context-path for assets.
$ clj -M:build /uPortal-website
This command will copy all the needed files for the website in dist/.
The Clojure source files can be linted with the follow command:
$ clj -M:eastwood
The Clojure source files can be checked and formatted with the follow commands:
$ clj -M:cljfmt check$ clj -M:cljfmt fix
Note that a Git pre-commit hook has been added to fix formatting issues.
Here are some design decisions for this project:
- Use libraries instead of a tool or framework. This has already paid off when the Markdown library broke and fell out of active support. It was easy to replace it with a new Markdown library.
- Clojure for the language. It's a simple, concise language that packs a lot power in a few lines of code.
- Make it easy for non-developers to add/update pages. Markdown is well known, so non-devs can just add/modify .md files in the repo.
- Target static website (with limited JS usage). We don't want this to be an additional burden on our community to maintain or fund. Upgrading WordPress and managing addons can be a pain.
- Have modest goals of a simple marketing/info site. Do not turn the uPortal site into an app.
- Stasis - the key library for developing this static website
- Blogpost on using Stasis - inspiration and basis for this repo
- Repo tag for the above blogpost - the author captured the code for his blogpost in this tag
- Clojure CLI Guide - if you want to know about the deps.edn
- How to use deps.edn with Stasis - there is a long pair of comments by Jag Gunawardana that contains his setup for Stasis that uses deps.edn and supports ClojureScript/Shadow-cljs