From ccb723f9979fef3f32e4d581bb738621db413e6c Mon Sep 17 00:00:00 2001 From: Adam Skrzymowski <35405850+adamskrz@users.noreply.github.com> Date: Fri, 10 Jan 2025 23:16:54 +0000 Subject: [PATCH] Add readme info on admonitions --- README.md | 144 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 101 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index b67e498..b0c5d78 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # Warwick Tech Crew Website + > This is the public website for Warwick Tech Crew, written using [Docusaurus](https://docusaurus.io). ## Contributing to the Wiki -The [wiki](https://warwicktechcrew.co.uk/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. + +The [wiki](https://warwicktechcrew.co.uk/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). +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](https://docusaurus.io/docs/markdown-features). @@ -16,7 +18,9 @@ You can also find more information about contributing on the [Contributing Guide](https://warwicktechcrew.co.uk/wiki/resources/contributing). ### 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): + ```yaml description: [Description of the page] sidebar_custom_props: @@ -24,11 +28,13 @@ sidebar_custom_props: ``` ### 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: + ```yaml --- additional_authors: @@ -37,7 +43,9 @@ override_authors: ``` ### Resources + You can add resources with the following frontmatter: + ```yaml --- resources: @@ -48,7 +56,9 @@ resources: ``` ### Shortlinks + Shortlinks can be added to provide a shorter link to the wiki page. The first shortlink will be shown in the sidebar: + ```yaml shortlinks: - mainShortlink @@ -56,6 +66,7 @@ shortlinks: ``` Section shortlinks can also be used to direct the user to a specific heading (e.g. `#section-heading`): + ```yaml sectionShortlinks: - shortlink: heading @@ -63,12 +74,15 @@ sectionShortlinks: ``` ### Images + Images can be added in the following Markdown format: + ```md ![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: + ```md
![Alt Text](file-name.txt) @@ -77,6 +91,7 @@ These can be made into a gallery format (i.e. showing them side by side) by wrap ``` These can be made full width by wrapping them in a `img-full` class div: + ```md
![Alt Text](file-name.txt) @@ -84,26 +99,48 @@ These can be made full width by wrapping them in a `img-full` class div: ``` ### Hero Images + Hero images can be added to the top of a page by adding the following front matter: + ```yaml 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). +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: + ```yaml disable_banner: true ``` +### Admonitions + +[Docusaurus has extra syntax to create "admonitions"](https://docusaurus.io/docs/markdown-features/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: + +```markdown +:::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). +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: @@ -111,51 +148,60 @@ 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: Amanda Fleming - - role: Prime Minister - name: Who the f*ck knows anymore - links: - - name: Images - label: Happy - url: https://unsplash.com/photos/m6BphieLlwA + - 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. + +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](https://dash.cloudflare.com/). +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](https://dash.cloudflare.com/). ## 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](https://nodejs.org/en/download). -Then, clone the website through SSH. You'll need to install [Git](https://git-scm.com/downloads) to do this, and setup a SSH key. +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](https://nodejs.org/en/download). + +Then, clone the website through SSH. You'll need to install [Git](https://git-scm.com/downloads) to do this, and setup a +SSH key. + ```bash git clone git@github.com:WarwickTechCrew/tc-website-wiki.git ``` Change into cloned directory + ```bash cd website ``` Install npm modules + ```bash npm install ``` Run the development server: + ```bash npm start ``` @@ -163,31 +209,42 @@ npm start This will start a live-reloading web server at [http://localhost:3000](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 + +- `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 + +- 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](https://gitmoji.dev/) 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 +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](https://gitmoji.dev/) 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: + +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: + ```bash npm run lint ``` @@ -196,10 +253,11 @@ 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. +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. \ No newline at end of file +Note that the build command must be `npm run shallow-build` to avoid issues with the changelog and Git history.