How to add new notes
This repository is the Hugo-based version of the old valerionew's repository and it uses the Bear theme. While the content is the same, there are some differences in how you can contribute to it compared to the old valerionew's repository. The structure of this wiki is the same as the README of the old valerionew's repository, so thanks valerionew.
In this wiki, you'll discover the instructions for contributing to this project. Are you here to add your notes? If so, please read below and thank you!
If you find the wiki poorly written, don't have enough time to learn the process, or feel overwhelmed by it, you can send the files directly to us here (with max 5GB as size limits, but please try to keep them smaller than the maximum limit).
For those unfamiliar with Hugo, all the files in the content folder will be translated by Hugo into a unique index.html file within the public folder, serving as the webpage.
For those familiar with Hugo, this website appears to be quite basic.
There's a trade-off between harnessing the full power of Hugo and maintaining simplicity for contributors who may not be familiar with Hugo.
This repository contains files that will be displayed on the web page. Contributors should navigate to the folder corresponding to the subject for which they have notes and then add their notes there. Once the changes are approved by the maintainers, the web page will be automatically updated and built.
Inside the "static" directory, you will discover a hierarchical structure of folders, one for each year. Within these "year folders", you'll find additional folders dedicated to individual subjects (only those with available notes). If your subject does not exist, you have to create a new folder on Github (see below). This is where you should place your notes.
NOTE: keep in mind that GitHub won't accept files of unlimited size; the limit is 100 MB per file in a commit. This means you can add multiple files, but each one must be under the 100 MB limit. If, for instance, your file is a PDF generated from handwritten notes, you may find that its size exceeds this limit. If you can't compress it to meet the size requirement, you won't be able to add it to GitHub. In such cases, consider storing the file in a shared cloud folder (Google Drive, OneDrive, Dropbox, etc.) and then provide a link to it on the webpage (as explained below).
Within this repository, you'll encounter two categories of resources:
- Files
- External content (links)
→ Files encompass items such as notes, forms, and diagrams. They are usually included as files when the author hasn't already made them accessible on the internet through their personal platform.
→ Conversely, external content pertains to resources published by the author elsewhere and linked within the HTML page. External content can also be included as "mirror" files in case the original source becomes inaccessible. While prioritizing the original source as the primary link is recommended, it's advisable to keep files as mirrors.
All files in this collection need to be released under open licenses. The repository's default license is Creative Commons BY-NC-SA 4.0, which is applicable unless stated otherwise, except for mirror files.
❗ Do you have multiple files? If you can zip all of them in one compressed folder, it's like one file (with .zip extension), so continue down below for instructions, otherwise if you want to keep them separate (like multiple pdfs), see these instructions.
To contribute to the collection, you have two options:
-
If you don't already have one, create a Github Account and follow the steps outlined in the section below to make a pull request. This will greatly assist me in validating your contribution.
-
Alternatively, you can reach out to me via email, and together we can determine the most suitable method for exchanging the note's files/links to be added on the website.
The process involves creating a fork of this repository, which results in your own editable personal copy. After you've made your contribution, it's necessary to initiate a pull request. This enables me to integrate your modifications into the main repository, which in turn generates the visible online page.
Obviously if you are a pro user, this changes can be made on your local machine too.
-
Create a fork of the project. This action will generate your individual copy of this repository, which you can then make modifications to:
From now we work on your fork repo.
-
If you have files to include, add them via the button (as in the image below) on the GUI or employ the drag-and-drop method: navigate to the subfolder related to the course and drag the files into the "static/FOLDERNAME" folder. Subsequently, you'll be prompted to make a commit, which refers to individual basic changes made to files within Git. Don't forget to provide it with a descriptive name! For additional insights, refer to the section on files.
❗ WARNING: FILE AND FOLDER NAMES MUST NOT CONTAIN SPACES. Instead, you can use underscores or connect words (as in the image below) for both your file and folder names. This applies to any folders you need to create, especially in cases where there are no existing notes for that specific subject. Here you can find instruction on how to create a folder on Github.
❗WARNING: THERE IS A NEW LIMIT OF 25MB GIVEN BY THE GITHUB WEBSITE. So, if your notes are bigger than this limit, you have to add your notes and change the markdown files (as described below) on a local fork on your PC, not on the website. The procedure is the same as described in this wiki, but you'll need Git installed on your PC in order to clone the repo, make changes and push them online in a pull request.
➡️ Look here for help. For a GUI alternative to command line Git, you can use Github Desktop. -
Next, you'll need to incorporate a link to the resource to ensure others can easily access it. To achieve this, you should insert a link within the "_index.md" file located in the "content" folder. You can either use github.dev or open the file and clicking on the edit icon.
### Chemistry (only if does not exist) * Course notes by _Mario Rossi_ - [Download](1/Chemistry/rossi-chemistry.pdf)Or:
### Chemistry (only if does not exist) * Formulary by _Mario Rossi_ - [Direct Link](https://external-link.com/resource) - [Mirror](1/Chemistry/formulary.pdf]) {{< asterisk >}} <!-- or --> * Course notes by _Mario Rossi_ - [Folder](https://external-link.com/resource_cloud_folder) {{< asterisk >}}❗ WARNING: YOU DON'T HAVE TO WRITE
[Download](static/1/Chemistry/rossi-chemistry.pdf), because Hugo will take care of that, you have to write only the relative path from the "static" folder !-
If you're linking to an external resource, remember to include the asterisk that identifies such resources: (*) (
{{< asterisk >}}in the markdown file). Proceed to make the commit exactly as described above, ensuring you use a meaningful name! -
If the subject you are contributing notes for does not currently exist, please ensure to include its name in the table of contents located at the beginning of the "_index.md" file. You can follow the instructions provided here for linking to heading IDs. Alternatively, if you omit this step, the maintainers will take care of adding the information on your behalf.
(See the image below for an example, please ensure that the item names are in the correct order.)
-
-
Once you've completed the process of incorporating changes, it's time to initiate a pull request. This action informs me that your additions are ready for review, facilitating their integration into the page. So, on the main page of your forked repository, you will find a section where GitHub asks you to either contribute or sync your fork. Clicking on 'Contribute' will allow you to open a pull request:
Here, you'll select "Compare across forks" and choose your fork as the head repository.
At this point, you can review your changes and proceed to open the pull request. The proposed changes will be checked, reviewed, and added to the main repository. After a few minutes, they will be available on the page: https://github.com/valerionew/triennale-elettronica-polimi/
-
If you're making your first contribution to this website, please ensure to include your name in the list within the
contribute.mdfile. -
However, if my notes for a single subject are contained within multiple PDF files, how can I upload and display all of them on the website? In this scenario, please refer to this section of the wiki.
Please see the Common issues section if you encounter problems.
-
If possible, please ensure that the license is included within the file, preferably placed on the first page. If you're uncertain about which license to apply, you can opt for the default license, and include the statement "This work is licensed under Creative Commons CC-BY-NC-SA-4.0" along with a hyperlink to the license: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en.
If incorporating the license directly into the file isn't feasible, kindly state the chosen license explicitly within the pull request description (place an "x" in the selected checkbox, which is automatically displayed while 'pull-requesting').
-
When naming the file, consider using a format like
courseAuthor.pdforcourseFormularyAuthor.pdf(mainly to have different names for the added files). -
In the case of contributing multiple files, we suggest establishing a subfolder within the course's directory to organize the content effectively. Then be consistent with the link in the markdown index (as said at point 3).
Please remember not to include spaces in the names; Markdown may not function as intended when creating links.
On your Github pull request page, the Netlify bot provides a preview link to the webpage shortly after you've submitted the pull request, usually within a few minutes. Click on this link to test the website. If you encounter any errors, you can make the necessary adjustments to your pull request.
For those more experienced, another option is to clone the repository. Using the latest version of Hugo, you can then test the website on your localhost to evaluate your changes even before creating a pull request.
See here for example and the testing section of the wiki.