¶ Zoom
Wiki.js' default settings zooms in quite a lot. The navigation bar and table of contents often cover the majority of the page on desktop devices: this can be distracting and visually discomforting.
There are two solutions to this:
- Zoom out using your browser, this is
"ctrl" + "-"on Windows and"Command" + "-"on macOS.- Use the print button and cancel the printing with
escto minimize the navigation bar.Refer to the heading for printing below for more information on the printing option.
Unfortunately, the print button is the only option to remove minimize the file navigation bar as far as I know.
¶ Navigation
¶ Content Table
Each year will have its own header in the home page. There will be a table containing the links to the pages available in the Wiki.
- Bold text indicates modules
- Italic underlined text indicates submodules
- Blue underlined text indicates specific topics. Click on these to be redirected to its page.
The table is divided into the autumn and spring terms.
1. Content table
¶ Navigation Bar
You can also explore the pages in ChemEng Wiki using the navigation bar on the leftmost part of the page.
2. Navigation bar
3. Folders
4. Pages
¶ Table of Contents
Each page has its own table of contents. Clicking on a header will redirect you to that section of the page. The table of contents only show the first two levels of headers.
5. Table of contents
You can click the ChemEng Wiki on the top left corner of the page to be redirected to the homa page.
¶ Printing
If you need physical copies of the page, you can click on the Printer Format icon located below the table of contents.
6. Print Format icon
¶ Hypothes.is Annotations
ChemEng Wiki uses Hypothes.is to provide highlight and annotation support. You'll need to create an account to use it.
¶ Creating a Hypothes.is Account.
7. Hypothesis Sidebar
- You should see these icons on the top right corner of the page. Click the left-arrow (<) option.
8. Sign up on Hypothes.is
-
You will see a panel appear on the right hand side with a message prompting you to sign up or log in. If this is your first time using Hypothesis, please create an account. It does not have to be your Imperial student email address.
-
Once you have successfully created your account and logged in, you can create annotations or highlights onto the page. Simply select the text and slect one of the two options.
9. Options to annotate or highlight
It is crucial for you to understand whether your annotations are made public or private. Please read our emphasis below.
¶ Public Annotations and Errors
If you find an error and do not feel comfortable with editing the page directly, you can use public annotations to highlight them. It would be nice if you could please add a short description of the error with the annotation.
You can definitely make amendments to the page directly: all users of ChemEng Wiki have edit permissions. All changes can be reverted because we have version control (every version of the page is recorded in History).
Another option is to contact your year's webmaster through Microsoft Teams if you want to discuss the corrections with us.
We will monitor public annotations on a regular basis and strive to address the issue promptly.
¶ Private Annotations
For annotations or highlights you use for your personal studies, please ensure that these are only visible to you (or your private group).
When making annotations, you should choose the Only Me option when your group is set to Public.
10. Please choose Only Me for personal notes
You can also change to a private group through clicking on the option besides the Hypothesis logo. You can create a new private group with the option in the bottom.
11. Change to a private group
You won't see an option to make you annotations public if you switch to a private group.
12. No Public Option
Your annotations will be saved and can be accessed again in your next visit. Markdown formatting is used for annotations.
Highlights are made public by default so please give extra attention to this. Thanks!
¶ Comments
At the bottom of each page, you will find a comment box. Feel free to use the comment section to discuss topics or ask questions. Markdown formatting is used for comments.
13. Comments
Clicking on either the View Discussion or New Comment options below the Table of Contents will redirect you to the comments section.
14. Click these to be redirected to comments
¶ Search Bar and Tags
Our website also has a search bar and "filter by tags" option at the top of the page. I personally recommend using the navigation bar or the tables in the home page instead. Tags are a work in progress and the search bar does not always give the best results.
15. Search bar and tags
¶ Accessibility
The department has requested that all of our content is made accessible. We strive to follow a few guidelines from the Web Content Accessibility Guidelines 2, which are detailed here.
¶ Relevant Accessibility Commitments:
- 1.1 Text alternatives for any non-text content
- One possible caveat for this is if maths written in latex is not classed as text in this sense. I cannot think of another reasonable way maths could be classified
- 1.2 Alternatives for time-based media, i.e. video and audio
- We host nothing of this sort, if we did captions or a transcript would need to be provided
- 1.4 Distinguishable
- This involves:
- Colour: Making sure colour is not used as the only visual means of conveying information. This is addressed below in the context of the PMO course
- Contrast: the visual presentation of text has a contrast ratio of at least 4.5:1. 3:1 is the minimum recommended by ISO-9241-3 for healthy observers, 4.5:1 is proposed by WCAG based off of 20/40 vision being average for an 80 year old user. From checking info, warning, and error boxes they all appear to comply.
- This involves:
- 2.4 Navigable
- This involves:
- clearly labelling what any links are or having obvious context
- page titles
- bypass blocks (I don't understand what this means. They describe as "bypass blocks of content that are repeated on multiple web pages)
- This involves:
While we cannot meet all guidelines, like 3.1.1 changing the default language of a page, we have tried to meet 1.1 providing captions and alt-text for images. alt text is described within the html img tag, the caption is a centered <p> tag underneath.
Colour is discouraged as being the only visual means of conveying information. This is currently an issue in the 3rd year PMO course, and I'm not sure how it should be addressed. Possibly with an identifying capital greek letter, e.g.
| Colour | Meaning |
|---|---|
| $$\color{blue} \text{Blue } \Upsilon$$ | Objective Function |
| $$\color{red}\text{Red } \Xi$$ | Equality Constraint |
| $$\color{green}\text{Green } \Lambda$$ | Inequality Constraint |
| $$\color{purple}\text{Purple } \Gamma$$ | Variable Bounds |
However, this is then an issue should any of those letters be required in lecture notes. I'm not sure what some good obscure latex to use would be.
¶ Page Edits
All users of ChemEng Wiki have edit permissions. To edit a document you can click the Page Actions option on the top right corner.
16. Page Actions
In the case that you want to edit anonymously:
- First access the Profile page by clicking the Account icon on the top right hand corner. You can also visit the page directly with this link: https://chemengwiki.com/p/profile
- Under 'My Info', you can change your displayed name to anything other than your name.
17. Changing Displayed Name
All pages in ChemEng Wiki use Markdown, which creates formatted text from plain-text. Wiki.js supports the full CommonMark Specification. Below are some additional guidelines for aspects not covered in the Markdown editor.
¶ Tables
We use pipe (|) tables in our version of Markdown.
| **Name** | **Equation** |
| --- | --- | --- |
| Ideal Gas Equation | $$pV=nRT$$ |
| Shear Strain | $$d\gamma =\ \frac{dl}{h}$$ |
This gives:
| Name | Equation |
|---|---|
| Ideal Gas Equation | $$pV=nRT$$ |
| Shear Strain | $$d\gamma =\ \frac{dl}{h}$$ |
¶ Images
In order to provide alternative text and image captions, we use HTML for all images. Markdown images also are not center aligned so please refrain from using them.
<img src="https://chemengwiki.com/tutorial/pageactions.png" style="width:250px" alt="Page Actions">
<p style="font-size: 14px; text-align: center; color: grey">
16. Page Actions
</p>
- The link leads to your image uploaded into the assets folder; I'll write about the assets folder below
- The width should be in pixels as opposed to percentages to better support mobile users (it gets really small when you use percentages); I'm not so sure if this makes that much of a difference
- Alternative text should be included for accessibility
- Captions should be included for accessibility
¶ Troubleshooting Block Quote Themes
Sometimes the theme's {.is-something} gets escaped by Latex, HTML, or lists. Here I've added the ways I've resolved the issue.
¶ Latex Error
Latex equations may sometimes break the theme (not always, the example below actually works). Correct this by adding a backslash in one line before the theme.
>Latex Break
>$$\text{This is in } \LaTeX$$
>\
>{.is-warning}
Latex Break
$$\text{This is in } \LaTeX$$
¶ HTML Error
With HTML snippets, it's better to add spacing with the theme.
><br>
><img src="https://chemengwiki.com/1st_Year/Maths1/Assets/maths1_1/1.png" style="width:200px" alt="[ENTER DESCRIPTION]">
><p style="font-size: 14px; text-align: center; color: grey">
>1. [ENTER DESCRIPTION]
></p>
>{.is-warning}
![[ENTER DESCRIPTION]](https://chemengwiki.com/1st_Year/Maths1/Assets/maths1_1/1.png)
1. [ENTER DESCRIPTION]
{.is-warning}
for instance, breaks. This doesn't.
><br>
><img src="https://chemengwiki.com/1st_Year/Maths1/Assets/maths1_1/1.png" style="width:200px" alt="[ENTER DESCRIPTION]">
><p style="font-size: 14px; text-align: center; color: grey">
>1. [ENTER DESCRIPTION]
></p>
>
>{.is-warning}
1. [ENTER DESCRIPTION]
¶ Markdown List Error
>- Markdown Lists
>- do not like
>- your themes.
>{.is-warning}
- Markdown Lists
- do not like
- your themes.
Fix this by adding spacing and a backslash. Both are necessary.
>- Markdown Lists
>- do not like
>- your themes
>- but there's a way to solve this!
>
>\
>{.is-warning}
- Markdown Lists
- do not like
- your themes.
- but there's a way to solve this!
This is true for both ordered and unordered lists.
¶ Content Creation
¶ GitHub Access
ChemEng Wiki is synced with Git and we have a private remote repository on GitHub. It may be much more convenient to push to the remote repository for large changes like new content and uploading images. If you would like to receive access to this repository, please contact one of the Webmasters.
¶ Git Push and Scripts
Exert caution when pushing changes in Git onto pages with JavaScript
Scripts are not stored in Markdown files. Pushing changes through Git will delete the entire script, ensure scripts are backed up before doing this.
JavaScript demonstrations will stop working if the scripts are erased. These can be a helpful indicator that a Git push was made without the scripts being added again.
¶ Assets
Images are placed in Assets folders. It should be easier to understand how they are organized if you see the folder structure in the repository. Here's a screenshot from my VSCode.
17. Assets folder structure
The Assets folders are placed in the same folder as the page markdown files. Within these Assets folders are specific folders for each page.
You might notice that the images here are named numerically: this is not necessary for newer content. I just found it convenient to have a script sort them in order during the conversion from Confluence.