Thanks for your interest in helping us maintain our course notes! We are happy to consider contributions from faculty and students to help make these notes easier to use and improve their correctness.
These notes are built using Docusaurus, a modern static website generator. To use it, you'll need to have the following installed:
-
an LTS version of node.js, which can be checked by running
node -v. Currently that's node.js 14.x, but confirm with the official site. -
The yarn package manager, version >= 1.5 (which can be checked by running
yarn --version). -
Visual Studio Code. This is not strictly necessary, but we encourage it since we use various extensions to make working on the site easier.
To install the dependencies, use:
yarn installTo develop the site, use:
yarn startThis command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
If you want to make a change, please use the following GitHub workflow:
- fork this repo on GitHub
- clone your forked repo to your local machine,
git clone https://github.com/{your username}/Intro2C - create a new branch off of the
mainbranch,git checkout -b {new branch name} main - make your changes and save
- check it builds successfully,
yarn build - check to see which files have changed,
git status - stage these changed files in git,
git add file1 file2 ... - commit your changes,
git commit -m "Made the following changes..." - push your commits and branch to your fork,
git push origin {new branch name} - create a Pull Request on GitHub
- add a description about what you changed and anything the maintainers need to know
Markdown documents can use the Markdown FrontMatter metadata fields, enclosed by a line --- on either side. We use id, title, sidebar_position, and description. However, we do NOT use slug for it.
To create a production build, use:
yarn buildThis command generates static content in the build/ directory and can be served using any static contents hosting service, for example: GitHub Pages.
To build and deploy to GitHub Pages, use:
-
Follow step 1 - 5 in Docusaurus's Triggering deployment with GitHub Actions
-
Deploy your site to Github Pages, run:
- For Bash:
GIT_USER=<GITHUB_USERNAME> yarn deploy- For Windows
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy- For Powershell
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.
To prevent table diagrams overflowing (and having the horizontal scrollbar on narrower viewports), we use a simple technique to convert them to images. This allows us to have responsive diagrams with less effort and minimizes HTML syntax on our pages.
Tool Recommendation: Firefox Browser (easier to make screenshots)
-
Run the app (
npm run start) -
Go to the browser
-
Go where the table you want to convert is
-
Right click, select "Take Screenshot"
- Select an area that encloses the whole table
-
Make any adjustments necessary when cropping (avoid having unnecessary space)
-
Click Download
-
Save image to the
/static/imgfolder in the repo -
This is how it should end up looking like:
- Use markdown to place the image wherever you need:
