<br /> <div align="center"> <a href="https://github.com/UWCS/stardust"> <img src="static/images/dots_logo_bg.png" alt="Logo" width="120" height="120"> </a> <h3 align="center">Stardust</h3> <p align="center"> <i>UWCS' Static Website</i><br> <a href="https://uwcs.co.uk">https://uwcs.co.uk</a> </p> </div>  <div align="center">

[![Contributors][contributors-shield]][contributors-url] [![Issues][issues-shield]][issues-url] [![Stargazers][stars-shield]][stars-url] [![Forks][forks-shield]][forks-url] [![build][build-shield]][build-url]

</div>

Built With

[![rust][rust-shield]][rust-url] [![zola][zola-shield]][zola-url] [![tera][tera-shield]][tera-url] [![chrono-english][chrono-english-shield]][chrono-english-url] <br><br> [![markdown][markdown-shield]][markdown-url] [![html][html-shield]][html-url] [![js][js-shield]][js-url] [![css][css-shield]][css-url] [![sass][sass-shield]][sass-url] [![bootstrap][bootstrap-shield]][bootstrap-url]

</div>

Project Info

Stardust is UWCS' static website, created by Owen and currently maintained primarily by Raven.

The website's HTML is generated from content written in [Markdown][markdown-url], using Zola, which has an integrated Jinja2-like templating engine Tera.

Custom forks of Zola & Tera are used - make sure to follow the installation instructions for setting the website up locally!

Stardust replaced our old website Dextre from the 2023/2024 academic year onwards.

GitHub Actions workflows rebuild and deploy to https://uwcs.co.uk on push to master.

Contacts for queries
- Some known issues
Installation
Contributing
- Making changes
- What to do if something weird happens
  - GitHub Actions failures
  - Everything else
Section-specific information
Example Markdown Pages
- News
- Events
Misc
- Room Lookup
- Shortcodes in CMS Editor
The Not At All Comprehensive List Of Todos

Contacts for queries

This README, and others, such as the merch README, contain a lot of useful info, please give them a read to see if these help solve your issue - even if they don't, some of the details may help someone assist you with your query :)
Raven is the current primary contributor, you're welcome to contact them for any queries, feedback, help setting up/contributing etc
- You can reach them via raven0034 on Discord
If you cannot reach them, join our Discord, and send a message in the tech-team channel, where the Tech Officers & Sysadmins can try and help

Some known issues

Installation scripts not functioning as intended post-migration from Owen's Zola fork to Raven's Zola fork
- The release paths differ on Raven's fork since it scraps Owen's GitHub Actions workflow and instead uses the (now fixed) pre-existing GitHub Actions workflow from upstream
- Also needs to account for aarch64 vs x86_64 releases properly, where on Owen's fork, only the latter was relevant
- Nix stuff does not point to the new fork currently
- Raven to fix Very SoonTM
(Not entirely confirmed) some Windows-specific inconsistencies in html generation causes some note shortcode usages to render incorrectly
- First observed on upgrading and migrating Zola forks
Campus map links are broken due to the uni shifting to a new system for Reasons - issue is being deferred to new events site when it lands

Installation

1. Cloning the project

Clone this repository using git clone --recurse-submodules
- Currently, the repository has a theme submodule stardust-theme
  - Required for the website to correctly function
  - Contains most of the formatting for the website, using [Sass][sass-url] and [Bootstrap][bootstrap-url]
- For contributors: make sure to read the submodules information section before starting changes
When pulling changes, use git pull --recurse-submodules (assuming Git 2.13+)
- If you don't want to type --recurse-submodules each time, run once: git config submodule.recurse true (git config --global [...] to apply to any repos you have)
The theme submodule references a specific commit hash, and the repository exists in a "detached state"
- This can cause some issues when contributing
  - This pulls the exact commit reference in a "detached state" from the branch, see the Contributing section for mitigating issues from this when contributing

2. Zola

Hopper/NixOS

Install fork of Zola (currently [Raven's fork][zola-url]): nix profile install github:UWCS/stardust

Other Platforms

Install fork of Zola
- install-linux.sh, install-mac-m1.sh and install-windows.ps1 exist - if these fail, you can follow their steps manually:
  1. Download latest pre-built release for the relevant platform, produced by GitHub Actions
  2. Places the zola binary in ./bin
  3. Adds zola to PATH
- If your platform is not supported/you're modifying Zola yourself:
  - Install Rust (see rustup.rs)
  - install-source.sh exists, which builds Zola from source - this can take a while (e.g. on Raven's M1 MacBook Pro, it can take around 5 minutes)
  - To do this manually:
    - Clone the fork of Zola: git clone https://github.com/raven0034/zola.git
    - Change directories: cd zola
    - Run cargo install --path .
      - For more info on Cargo, check out the docs

Debugging & Extra Info

Errors about missing square root means you are not running the fork of Zola
Errors that include main panicked [...] invalid time means you are running Owen's fork of Zola, which is outdated
[Raven's fork][zola-url] is based on Zola 0.20 (rather than 0.17.2 as previously), with the following:
- Upstream changes merged on top of Owen's changes (for both Zola and Tera - [Raven's Tera fork][tera-url])
- Zola's tests and GitHub Actions workflows fixed
- An issue in chrono-english fixed where it failed to appropriately handle 12:XXPM times correctly
  - The author previously blindly added 12 to any afternoon times, resulting in a panic in chrono for any 12:XXPM where 24 is passed to a function that expects (reasonably) a range of 0 - 23
  - [Raven's chrono-english fork][chrono-english-url] is forked from Nukesor's fork. The original author, until recently, did not update the repository to reflect the changes made in the 0.1.7 release on Cargo

3. Deploying the site

Run zola serve from the project root - this rebuilds on changes, and serves to http://127.0.0.1:1111
- Raven has experienced issues with this quite frequently, so, alternatively:
  1. Start a http server
    - For most POSIX-like shells:
      - python3 -m http.server --directory public -b 127.0.0.1 1111 > web.log &
    - For Powershell:
      - Start-Process -NoNewWindow -FilePath "python" -ArgumentList "-m http.server 1111 --directory public --bind 127.0.0.1" -RedirectStandardOutput "web.log"
  2. Run zola build --base-url http://127.0.0.1:1111 --force - needs to be re-run for any changes
  - You may also find this alternative preferable when contributing so you can make larger changes without it redundantly building on every save
- IMPORTANT
  - In config.toml, ignored_content contains "**/archive/*"
  - content/events/archive & content/news/archive combined contain 3000+ pages
  - To avoid weirdness (needs further investigation) with some changes not properly showing, zola build with --force is usually used - forcibly removing public/, and triggering a full rebuild
  - 3000+ pages can take a while to build (2-3m on sites on localtoast, 30-40s on W11 on Raven's desktop with an i7-12700k, and 5-10s on Raven's M1

Stardust

Install / Use

README