Warwick Tech Crew Website

This is the public website for Warwick Tech Crew, written using Docusaurus.

Contributing to the Wiki

The wiki is a collection of information that may be useful to Tech Crew members and is open for everyone to see and contribute to. Docs are written using Markdown (a simple text format similar to that used in Discord and Whatsapp), and are stored in the /wiki directory.

To contribute, you will need to a GitHub account. You can then edit the files directly on GitHub or clone the repository using the instructions below. Alternatively, contact someone familiar with the website (such as Josh Heng to make the changes for you).

You can find more information about formatting here.

You can also find more information about contributing on the Contributing Guide.

Front Matter

Each doc file should have front matter at the top of the page that defines its description and emoji (e.g. for embeds):

description: [Description of the page]
sidebar_custom_props:
  emoji: 🎭

Wiki Authors

By default, the site will show the name of all the contributors for each page. This is determined from the name you use on GitHub/the name you have configured in Git. These names can be overridden in the file src/lib/author-names.ts.

It is also possible to add additional contributors or override all the contributors for a wiki page by adding the following front matter to the top of each doc file:

---
additional_authors: <comma separated list>
override_authors: <comma separated list>
---

Resources

You can add resources with the following frontmatter:

---
resources:
  - name: [Resource name]
    url: [Resource URL]
    author: [Optional - resource author]
---

Shortlinks

Shortlinks can be added to provide a shorter link to the wiki page. The first shortlink will be shown in the sidebar:

shortlinks:
  - mainShortlink
  - secondaryShortlink

Section shortlinks can also be used to direct the user to a specific heading (e.g. #section-heading):

sectionShortlinks:
  - shortlink: heading
    hash: section-heading

Images

Images can be added in the following Markdown format:

![Alt Text](file-name.txt)

These can be made into a gallery format (i.e. showing them side by side) by wrapping them in a img-gallery class div:

<div class="img-gallery">
    ![Alt Text](file-name.txt)
    ![Alt Text](file-name.txt)
</div>

These can be made full width by wrapping them in a img-full class div:

<div class="img-full">
    ![Alt Text](file-name.txt)
</div>

Hero Images

Hero images can be added to the top of a page by adding the following front matter:

image: ./banner.jpg
image_alt: Image alt text

These will be shown in link previous and at the top of the doc page. Note that this image will be resized to cover the full page width and will always be in a banner-like aspect ratio, so make sure the image is suitable for this (i.e. the most interesting part of the image should be in the vertical middle, and top/bottom cropping shouldn't cause an issue).

A hero/embed image can be disabled from being shown as a banner with the following front matter:

disable_banner: true

Admonitions

Docusaurus has extra syntax to create "admonitions", similar to the one below:

Warning

The Docusaurus admonition syntax is different to that used by GitHub and Obsidian

You can use the types note, tip, info, warning, danger. We also have our own custom lore admonition. To add lore to a page use:

:::lore

This wiki was started in 2024. Contributing is a great way to procrastinate coursework!

:::

Updating Shows

Shows are stored in annual YAML files in shows/.

You can add notes to a term to be displayed above the shows (see Term 3 2019/2020), as well as links below the roles in a show (see photo galleries in earlier years).

The standard format is below:

year: 2012 / 2013

terms:
  - name: Term 1
    notes: This was a strange term, we don't talk about it.
    shows:
      - name: 'Tech Crew: The Musical'
        society: Tech Crew X MTW
        venue: Warwick Arts Centre Theatre
        people:
          - role: Tech Manager
            name: Joe Bloggs
          - role: Prime Minister
            name: Who the f*ck knows anymore
        links:
          - name: Images
            label: Happy
            url: https://unsplash.com/photos/m6BphieLlwA

Updating the Exec

The exec information is stored in src/components/home/the-exec.tsx, at the array at the top of the file. Images should be stored in static/images/home/exec and should ideally be compressed to 85% quality 300x300px jpegs.

Cloudflare Configuration and Rules

Discord does a silly thing where if a link is followed with !, it will include the ! in the link (which then causes the link to 404). To fix this, we have a Cloudflare redirect rule that removes the ! from the end of any URL. This can be managed on the Cloudflare dashboard.

Running the Website Locally

You will need to have installed Node.js v20 and NPM for this to work. If you haven't already done this, you can install the LTS version here.

Then, clone the website through SSH. You'll need to install Git to do this, and setup a SSH key.

git clone [email protected]:WarwickTechCrew/tc-website-wiki.git

Change into cloned directory

cd website

Install npm modules

npm install

Run the development server:

npm start

This will start a live-reloading web server at http://localhost:3000.

The following environment variables can also be added on deployment:

• SHORTLINK_URL: The base URL for shortlinks (e.g. https://wwtc.uk). If not defined, the site URL will be used

Assets

Images and assets can be stored in static/images. Please follow the naming convention for images to ensure that credit is given to the author, and please resize the images to 85% quality jpegs of a reasonable size.

Common sizes are:

• 16:9 aspect ratio with 800px width: general photos
• 3:1 aspect ratio with 3000px width: carousel images

Code and Commit Style

Git Usage

Please complete any work in your own branch related to the issue you are completing. You can click 'Create Merge Request' on the issue to do this, and then create a branch when asked.

When committing changes, precede your message with a Gitmoji so it's easy to see what you have done. The most common ones you may use are:

• 💬 :speech_balloon: - Add or update text and literals
• ✨ :sparkles: - Introduce new features
• 🐛 :bug: - Fix bugs
• 💄 :lipstick: - Add or update the UI and style files.
• 🚨 :rotating_light: - Fix compiler/linter warnings

After you have completed your work, remove the draft status from your merge and assign Josh to review it!

ESLint

We use eslint to ensure that our code is generally high quality and is formatted consistently. This will automatically be run whenever a merge request is created. This can be run with:

npm run lint

npm run lint:fix

If you are using an editor such as IntelliJ or VSCode, I'd recommend setting your editor to automatically run this whenever you save, and fix any issues.

Deployment

This website is deployed on Cloudflare Pages on the Warwick Tech Crew Cloudflare account.

Note that the build command must be npm run shallow-build to avoid issues with the changelog and Git history.