Contribution Guide

Hi! First of all, thanks for wanting to contribute to Notes@HKU!

You can contribute in a number of ways:

Adding new content

Contribute by adding new notes or sections to existing notes to expand the knowledge base.

Fix inconsistencies in existing notes

Help improve the quality of notes by fixing any inconsistencies or errors in the content.

Fix incorrect information

Ensure the accuracy of the notes by correcting any incorrect information.

Fix typos & fluency

Enhance the readability of the notes by fixing any typos, grammatical errors or suggest improvements in the fluency of the content.

The following guide will help you get started. If you are unfamiliar with Github, you can also simply leave a comment on the website!

Information about formatting

File structure

If you are planning to edit a page, you can click on "Edit on Github" at the bottom of each page, or click the Pen icon then "Edit note on Github". This will take you to the file on Github.

All notes are stored in the notes folder. Each note is stored in a folder with the same name as the note. The folder contains the following files:

  1. *.mdx - A page of the note. The name of the file is the url / slug of the page.
  2. meta.json - Contains metadata about the note. When adding new pages, you must update the pages array in this file.

Markdown syntax

The site supports Github flavored markdown.

In addition to standard markdown, we also support MDX, which allows you to use JSX components in markdown. The following are some advanced features that you can use:

Working and submitting changes

Contribution requires an understanding of Github and Git. If you are unfamiliar with Git, you can also leave a comment on the website!

Fork & clone this repository

Go to our Github repository and click on the "Fork" button in the top right corner. This will create a copy of the repository in your Github account. Then, clone the repository to your local machine by clicking "Code" and copying the URL.

git clone YOUR_URL

Create or edit content

We recommend using VSCode with a markdown preview extension to edit the notes. Change file association by Change language mode -> Markdown to enable markdown preview. Use the Markdown Admonitions and Markdown+Math extensions to view math and admonitions in the preview.

Some guide on writing notes:

  1. Keep notes concise, clear and to the point. Keep only necessary context.
  2. Use headings and subheadings to structure the notes.
  3. Always use admonitions to contain concepts, examples and useful information. Only write context, transitional sentences and less important information outside of admonitions.

Push changes to your fork

After you have made changes, commit them and push them to your fork.

git add .
git commit -m "Your message"
git push

Create a pull request

Head to your fork on Github and click on Pull request -> New pull request. Make sure the base repository is {REPO_OWNER}/{REPO_NAME} and the base branch is dev. Compare changes and create a pull request.

I'll review the changes and merge them if they look good!

On this page