Lallans Wabsteid Astro

This is the Scots Leid Associe website, implemented in Astro.

Gettin yokit

git clone https://github.com/joeacarstairs/lallans-wabsteid-astro.git \
  && cd lallans-wabsteid-astro \
  && npm install \
  && npm run dev

Contributing

All you need to edit the website

• Has a text editor or IDE and can use it to edit text files.
• Can write Markdown. (Beginners can learn in an afternoon by following the getting started guide!)
• Has a GitHub account.
• Can use Git to clone, pull, push, stage files, commit staged files, branch and checkout. Here's a great beginner's tutorial to Git and here's another great, interactive Git tutorial focusing on branching.
• Can use GitHub to make a fork and make a Pull Request back into the upstream repository. Here's a basic GitHub tutorial and here's a GitHub guide to forking.
• Can use a command-line terminal.
• Can use NPM to install dependencies and run scripts.

General guidance

1. If you haven't already, fork the repository, and clone your fork.
2. Make a suitably named branch on your fork.
3. Make your desired changes (see sections below for common cases).
4. Commit and push them on your branch.
5. Make a Pull Request to merge your changes into joeacarstairs/staging.
6. A code owner (probably the Scots Language Society Webmaster) will review your Pull Request, ask for any necessary changes, and when satisfied, merge it into joeacarstairs/staging. (This will update the staging deployment on staging.scotsleidassocie.org.)
7. Code owners will merge joeacarstairs/staging into joeacarstairs/production at their discretion. (This will update the production deployment on scotsleidassocie.org.)

Coding style

Coding style is enforced by ESLint and Prettier. These tools are run on a commit hook, and you will not be able to commit if they fail. Please refrain from using git commit --no-verify except in extraordinary cases, and make it clear in your Pull Request when you have done so.

Writing a news post

Follow this guidance alongside the general guidance.

1. Copy and paste an existing news article in both English and Scots. You will find these in src/content/news/en-GB and src/content/news/scots respectively.
2. Rename the news article following the existing pattern, which is the date of publication in YYYY-MM-DD format followed by the title in kebab case and the .mdx file extension. For example, 2023-12-24-eiks-an-ens-3000.mdx would be Eiks an Ens 3000, published on the 24th of December 2023.
3. Edit the news articles to contain your desired content.
4. Check it looks OK by running the website locally with npm install && npm start.

Adding an issue of Lallans

Follow this guidance alongside the general guidance.

1. Add the issue number to src/types/LallansIssueNumber.d.ts.
2. Add the original issue cover photo as src/images/lallans/issueXYZ.jpg, where XYZ is the issue number. Most of the examples are .jpg, but the file type isn't important.
3. Make a copy of the cover image that is scaled to 192 pixels wide. Name it issueXYZ-192w.jpg.
4. Copy one of the existing Lallans issues in src/data/lallans and name the copy issueXYZ.ts.
5. Edit the file you just made with the new issue's information, including the location of the correctly scaled cover image that you just made.
6. Import that data file into the Lallans data index file, src/data/lallans/index.ts.
7. Check that everything's working: the issue should appear at the top on the Lallans page, /furthsettins/lallans, and the issue information should appear at /furthsettins/lallans/XYZ. Check both the English and Scots versions.

Adding a Scotsoun release

Follow this guidance alongside the general guidance.

1. Add the release ID to src/types/ScotsounId.d.ts.
2. Add the original cover image as src/images/scotsoun/scotsounXYZ.jpg, where XYZ is the release ID. Most of the examples are .jpg, but the file type isn't important.
3. Make a copy of the cover image which is scaled to 192 pixels wide, and name it scotsounXYZ-192w.jpg.
4. Copy one of the existing Scotsoun releases in src/data/scotsoun and name the copy scotsounXYZ.ts.
5. Edit the file you just made with the new release's information, including the location of the correctly scaled cover image that you just made.
6. Import that data file into the Scotsoun data index file, src/data/scotsoun/index.ts.
7. Check that everything's working: the release should appear at the top on the Scotsoun page, /furthsettins/scotsoun, and the release information should appear at /furthsettins/scotsoun/XYZ. Check both the English and Scots versions.

Infrastructure

The deployment infrastructure for the website is in four parts: the domains, the SSL certificates, the hosting, and the CI/CD.

Domains

The website is served on two domain names: lallans.co.uk and scotsleidassocie.org. The lallans.co.uk domain is legacy, but will redirect to scotsleidassocie.org until at least September 2024.

Firstly, lallans.co.uk is registered with JoomlaWired, a hosting company specialising in hosting Joomla! and WordPress websites. We used to host a Joomla! website with them, hence the connection. We don't host anything with them any more, but we still rent the lallans.co.uk domain from them. The Scots Language Society Webmaster should have access to JoomlaWired.

Redirecting requests to lallans.co.uk to scotsleidassocie.org is handled by Vercel.

Meanwhile, scotsleidassocie.org is rented from AWS. Again, the Webmaster should have access to the AWS Console.

SSL certificates

The SSL certificate for scotsleidassocie.org is bought from AWS Certificates Manager. Again, the Webmaster should have access to the AWS Console.

Hosting

The website is hosted on Vercel. Because we have the free plan, unfortunately only the Webmaster can access the Vercel dashboard.

Vercel also handles redirecting from lallans.co.uk to scotsleidassocie.org.

CI/CD

Our CI/CD pipeline is, thanks to the fantastic integration between GitHub and Vercel, no-code! We just need to make commits to the repo to see them deployed automagically.

Ideally, we should check everything's working on deployment before everyone on the internet starts looking at it. For that reason, we have a staging deployment at staging.scotsleidassocie.org. To update the staging deployment, simply commit to staging by making a Pull Request and getting it approved by a code owner and then merged.

To update production, you'll want to first merge your changes into staging by making a Pull Request and getting it approved and merged. Once you've done that, given it five minutes to deploy, and you've checked that everything looks good on staging.scotsleidassocie.org, make a Pull Request to merge staging into production. Once that Pull Request is approved by a code owner, merge it in and it should update production in under five minutes.