Skip to content

Latest commit

 

History

History
133 lines (80 loc) · 4.19 KB

CONTRIBUTING.md

File metadata and controls

133 lines (80 loc) · 4.19 KB
Raw

Contributing

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.

Requirements

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.

Installation

To install the dependencies, use:

yarn install

Local Development

To develop the site, use:

yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Workflows

If you want to make a change, please use the following GitHub workflow:

  1. fork this repo on GitHub
  2. clone your forked repo to your local machine, git clone https://github.com/{your username}/Intro2C
  3. create a new branch off of the main branch, git checkout -b {new branch name} main
  4. make your changes and save
  5. check it builds successfully, yarn build
  6. check to see which files have changed, git status
  7. stage these changed files in git, git add file1 file2 ...
  8. commit your changes, git commit -m "Made the following changes..."
  9. push your commits and branch to your fork, git push origin {new branch name}
  10. create a Pull Request on GitHub
  11. add a description about what you changed and anything the maintainers need to know

Standardize frontmatter

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.

Releases

Build

To create a production build, use:

yarn build

This command generates static content in the build/ directory and can be served using any static contents hosting service, for example: GitHub Pages.

Deployment

To build and deploy to GitHub Pages, use:

  1. Follow step 1 - 5 in Docusaurus's Triggering deployment with GitHub Actions

  2. 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.

Miscellanous

Tutorial for Converting Table-like Diagrams into Images

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)

  1. Run the app (npm run start)

  2. Go to the browser

  3. Go where the table you want to convert is

  4. Right click, select "Take Screenshot"

  1. Select an area that encloses the whole table

  1. Make any adjustments necessary when cropping (avoid having unnecessary space)

  2. Click Download

  1. Save image to the /static/img folder in the repo

  2. This is how it should end up looking like:

  1. Use markdown to place the image wherever you need:
!["Alt test for accessibility"](/img/name-of-the-image.png)