Skip to content

Commit 121a18f

Browse files
melarbmelarb
committed
feat: add demo file and README
1 parent 0787c12 commit 121a18f

2 files changed

Lines changed: 545 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
2+
# Northeastern University Wireless Club (W1KBN) Intro to Git Workshop
3+
4+
Welcome to the repository for the Northeastern University Wireless Club Intro to Git Workshop.
5+
This repository contains the slide deck and related materials used for our LaTeX Workshop.
6+
7+
---
8+
9+
## Workshop Slides
10+
11+
A precompiled PDF of the slide deck is available in the [Releases](https://github.com/nu-wireless/git/releases/tag/2025-fall) section for quick viewing.
12+
13+
---
14+
## Workshop Instructions
15+
16+
### Using the Demo `index.html` File
17+
18+
We will be providing you with a demo `index.html` file for this workshop.
19+
The goal is not to teach HTML.
20+
The goal is to give you a simple file you can edit while learning Git, commit your changes, and, if time allows, publish it using GitHub Pages so you leave with something you can show.
21+
22+
You are not expected to know HTML, design websites, or write code for the page.
23+
Just look for the `<!-- EDIT HERE -->` comments inside the file and fill in your own information.
24+
25+
---
26+
27+
## What you will do with `index.html`
28+
29+
1. Download the demo HTML file from the Releases section or clone the repository containing it.
30+
31+
2. Edit only the sections marked with `<!-- EDIT HERE -->`.
32+
33+
* Replace placeholder text such as your name, major, interests, or links.
34+
* Remove the “MODIFY AS NEEDED” pill once you customize your skill tags.
35+
36+
3. Use Git commands to track your changes:
37+
38+
```bash
39+
git add index.html
40+
git commit -m "personalize my webpage"
41+
git push
42+
```
43+
44+
We will walk through these steps during the workshop.
45+
46+
4. If time permits, we will also publish your page using GitHub Pages so you have a live link that you can share.
47+
48+
---
49+
50+
## Hosting Your Page on GitHub Pages (if time allows)
51+
52+
There are two simple options. We will guide you through both during the workshop.
53+
54+
### Option 1: The simplest method
55+
56+
Create a repository named `yourusername.github.io`.
57+
58+
1. Create a new public repository named exactly:
59+
60+
```
61+
yourusername.github.io
62+
```
63+
2. Add `index.html` to the root of the repository.
64+
3. Commit and push.
65+
66+
Your site will then be available at:
67+
68+
```
69+
https://yourusername.github.io
70+
```
71+
72+
---
73+
74+
### Option 2: Any repository name
75+
76+
1. Use any repository name you prefer.
77+
2. Add `index.html` to the root of the repository.
78+
3. Go to:
79+
Settings > Pages
80+
4. Under "Build and deployment", select:
81+
82+
* Source: Deploy from a branch
83+
* Branch: main
84+
* Folder: root or docs
85+
86+
GitHub will generate a link to your site after it builds.
87+
This usually takes about one minute.
88+
89+
---
90+
91+
## What you should walk away with
92+
93+
By the end of the workshop, you should have:
94+
95+
* Used real Git commands on a real file
96+
* Learned how to push changes to GitHub
97+
* Optionally published a personal webpage
98+
* Created something small but polished that you can show others
99+
* Gained a working understanding of Git fundamentals
100+
101+
The focus is Git, not HTML.
102+
The HTML file is simply a hands-on way to practice and leave with something you can be proud of.
103+
104+
---
105+
## Compiling the Slides Yourself
106+
107+
### Intended Audience
108+
109+
This repository is primarily maintained by the Wireless Club Workshop Team.
110+
111+
The public can view the precompiled slide deck, but local compilation is primarily intended for officers. Successful compilation requires invoking the `--shell-escape` flag during build, as the source uses it to execute a Git command that retrieves the current commit hash for the footer.
112+
113+
To compile successfully, you must have a local clone of the repository that includes the `.git` directory. The build process depends on this metadata to parse the Git commit head through the `\iexec` command.
114+
115+
If you only download `main.tex` or a ZIP archive from GitHub, the `.git` directory will be missing and the version hash in the footer will not render correctly. In that case, you can still compile the slides by creating your own repository or removing the versioning command from the footer.
116+
117+
Officers with repository access can clone and compile directly. External users would need to fork or create their own repository to do the same.
118+
119+
---
120+
121+
### Requirements
122+
123+
To compile the slide deck locally, make sure you have:
124+
125+
* A LaTeX distribution such as TeX Live, MiKTeX, or MacTeX
126+
* The `minted` package
127+
(requires Python and Pygments; compile with the `--shell-escape` flag)
128+
* A LaTeX editor such as VS Code with the
129+
[LaTeX Workshop extension](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop), TeXstudio, or TeXShop
130+
131+
---
132+
133+
### Why Local Compilation Is Required
134+
135+
This presentation cannot be built online (such as on Overleaf) because it needs the `--shell-escape` flag, which allows LaTeX to execute external commands.
136+
To my knolwedge, Overleaf does not support user projects that invoke shell commands during compilation.
137+
138+
The `--shell-escape` flag is needed because of the following command defined in the source:
139+
140+
```latex
141+
\usepackage{iexec}
142+
\newcommand{\gitAbbrevHash}{\iexec{git rev-parse --short HEAD}}
143+
```
144+
145+
The `iexec` package runs the system command `git rev-parse --short HEAD` to automatically insert the current commit hash into the footer.
146+
This requires both Git and a repository clone with its `.git` directory intact.
147+
If you download only `main.tex` without the `.git` folder, the command will not return anything, and the “Version” field in the footer will be blank.
148+
149+
---
150+
151+
### How to Compile
152+
153+
1. Clone the repository
154+
155+
2. Compile using `pdflatex` (or any compiler) with the shell escape flag
156+
157+
```bash
158+
pdflatex --shell-escape main.tex
159+
```
160+
161+
If you are using VS Code with LaTeX Workshop, make sure the `--shell-escape` flag is included in your build recipe.
162+
163+
I personally have only ever compiled this slide deck with pdflatex, so I cannot speak for lualatex or any otehr compilers.
164+
165+
---
166+
167+
## Repository Structure
168+
169+
```
170+
.
171+
├── assets/ # Assets used in the slide deck
172+
│ ├── branching.png
173+
│ ├── git-logo.png
174+
│ ├── git-snapshot.png
175+
│ └── xkcd-git-comic.png
176+
├── demo/
177+
│ └── index.html # Demo HTML file for workshop participants
178+
├── README.md # This README file
179+
└── main.tex # Main Beamer slide deck source file
180+
```
181+
182+
---
183+
184+
## Troubleshooting
185+
186+
* **Blank version field in footer:** You are compiling outside a Git repository or missing the `.git` directory. You either need to be an officer with push access or create your own Git repo.
187+
* **Error's mentioning shell escape** Re-run compilation with the `--shell-escape` flag.
188+
189+
---
190+
191+
## Questions
192+
193+
If you have any questions or feedback, please reach out:
194+
* Contributor's Email: [elarbi.m@northeastern.edu](mailto:elarbi.m@northeastern.edu)
195+
* Workshop Email: [workshops@nuwireless.org](mailto:workshops@nuwireless.org)
196+
* Club Website: [https://nuwireless.org](https://nuwireless.org)
197+
198+
---
199+
200+
## License
201+
202+
This project is licensed under the
203+
[**Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License**](https://creativecommons.org/licenses/by-nc-sa/4.0/). <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1" alt=""> <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1" alt=""> <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1" alt=""> <img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1" alt="">

0 commit comments

Comments
 (0)