Week 1 - Principles, Practices, Presentations, Project management¶

Assignment¶

Plan and sketch a potential final project
Read, sign (add your name to) the student agreement and commit it to your repo
Work through a git tutorial.
Build a personal website in the class archive describing yourself and your final project. Refer to the lecture material for examples.
Upload parts 1 and 2, to the class archive.

Additional Personal Goals¶

Also some goals ¹

Goal	Resource	Notes
Learn Markdown	website	finding non-basic videos
Learn to Compress Files	Adam Stone Compressor	also review Neil notes
Make a website	past student research	look in my Google doc notes
final Project Orgnization	Kenny Documentation	find notes and files

Added Unexpected Bonus¶

learned to make animated gifs:¶

Claude results on Animated Gif creation From video:

Online tools - Upload a video to sites like ezgif.com, giphy.com/create, or imgflip.com/gif-maker. Trim the clip, adjust speed, add text if you want, then download.
Phone apps - GIPHY (iOS/Android) lets you convert videos from your camera roll or record new ones directly in the app.

Claude also suggested that my phone could do it. I use an Andriod and it does make them! So I took the video, edited it on the phone editing app. I replacd the one I originally had from Tenor with my own creation seen on the home page. However, i noticed it was 3MB and we have a 10MB per commit limit. So then I took it to the freeconvert.com file compressor. However, it still increased my objects file (see below).

GIT Objects¶

I noticed that my files being uploaded were bigger than I thought they should be. So I started to navigate around and figured out it was the .got/objects file that was so big. Claude's advice.

\camille-kanofsky\.git\objects  why is the objects file so big?

The .git/objects folder stores all your Git repository data - every version of every file you've ever committed. It gets big for a few reasons:

Common causes:

Large files committed - Images, videos, binaries (especially if you've committed multiple versions) Many commits - Git keeps history of everything Large files that were deleted - Even if you delete a file, Git keeps it in history Binary files that change - Like your .jpg and .png files - each change creates a new copy in Git

Given this informatoin I am going to ask the professors whether i need to try to cull the files to make more room and lesson my file size on the server.

Kenny Hu also suggested git gc, as an alternative to clean up the files, or a squash if i dont mind losing all the files. I need to know what the instructors would like to see in our git history before I proceed.

As a work around, I learned how to host images in my free github site area and then refer to them from my gitlab site. But on the recitation, I learned this is a no no... so I will stop doing that for the future..

The Work¶

GIT work¶

In our prefab we watched and followed a GIT tutorial from Coder Coder. It was actually my second time watching this particular tutorial. She made a very helpful video. Thank you Coder Coder.

Dr. Taylor gave us a GIT Lesson

On advice from Kenny Hu , I looked up another You Tube tutorial on using gitlab and git with the command line. Thank you, TestMU AI, https://www.youtube.com/@LambdaTest

The recitation had lots of information in the slides A few useful commands reviewed in the recitation:

command	description
git status	gives you a list of the files and thier status
git commit -m "message"	staging the files
git push	push the files up into the cloud
git add -p	patching ask about each file
git pull	use if you use more than one computer to sync up your files

KEY NOTES - push limit is 2 MB per commit

Website Limit 500 MB
make pictures >500 pixels

Website¶

Setting Up VSCode and MKdocs¶

I wanted to use VS code and MKdocs. Setting up VS code with the Gitlab was the first challenge. I followed Teddy Warner’s documentation and found that I didn't even understand step one.. LOL. So starting out a bit flustered, I decided to re-read the slides from today and start to work on the SSH key. Terminology is getting me a bit, but I'm a learner... so let's do this.

Step one - SSH - but first you have to see if you already have an SSH

STEP 1 - Open Git Bash.

STEP 2 - Enter ls -al ~/.ssh to see if existing SSH keys are present.

$ ls -al ~/.ssh
# Lists the files in your .ssh directory, if they exist

Step 3 Check the directory listing to see if you already have a public SSH key. By default, the filenames of supported public keys for GitHub are one of the following. id_rsa.pub id_ecdsa.pub

Problem Will Rogers - I didn't know what step 1 - GIT BASH meant.. So I turned to Claude and Claude explained GIT BASH to me.

Relative

AWE - yay.. Now that I knew I didnt already have an SSH key, I moved on to making the SSH keys as directed

Then I wanted to connect my VS code with the gitlab so I needed to git clone and use the SSH that I had added. After much fighting with the system… and a few trips to Claude.. And a hug from my son, I was able to go back into the command line and navigate to the right spot - the place in my computer (locally that I wanted to use for my repo) and use

git clone git@gitlab.fabcloud.org:academany/fabacademy/2026/labs/charlotte/students/camille-kan…

To successfully clone the site.

I needed to use the SSH keys and it kept wanting to use the HTTP method which would open up the github for authentication.

On a visit to Richard Shan of 2024 site, I found a a nugget about typing Python first & environmental variables.

He had many of the same errors that I did.. So I followed along with some of his fixes and they helped. I was able to clone my site

Then I needed to install MKDocs

Step 1: Initialize MkDocs in your project bash -m mkdocs new . Which creates: - mkdocs.yml (your config file) - docs/ folder with a sample index.md

Step 2: Test it works bash python -m mkdocs serve

Open http://127.0.0.1:8000 in browser - you should see your site!

Image Compression¶

from [Barbara Morrow}(https://fabacademy.org/2022/labs/charlotte/students/barbara-morrow/assignments/week02b/) site, she suggested tinypng
also Adam Stone. has an image resizer on his fab academy site.

Using Markdown¶

Let's talk about how I learned Markdown

I found a helpful you tube video from Technical Writing Group

'WWW.technicalwritingmp.com'

What they forgot to mention was that in order to use some of these advanced techniques I needed to add the following markdown extensions to my mkdocs.yml file. Much frustration -I wanted the emoji’s, footnotes, and internal linking.. so I had to do some more research to find out that I needed.

QUICK TIP CTRL+SHIFT+V To preview the mark down site

I found that I needed to add these extensions added to the mkdocs.yml

markdown_extensions:
  - toc
  - attr_list
  - footnotes  # Also needed for [^1] to work
  - pymdownx.emoji

But then it errored out with pymdownx.emoji. I needed to install the materials package.

So I needed pip - I tried to install the material package from the gitbash, from the terminal, from the command shell, but it said that I didn't have pip. So that was a rabbit hole of trying to add environmental variables. These really didn't seem to work and Claude said that I probably have multiple installs of Python. So then Claude suggested that I just add the “python -m” before the “pip install” see below to let them know it was Python script. And that worked for being able to install the materials package which allowed the emoji’s to show on the markdown page.

python -m pip install <package>
python -m pip install mkdocs-material

Great cheat sheet

Tables¶

The video did teach me to make tables, footnotes, and emoji's.

Left Aligned	Middle Aligned	Right Aligned
Hello	Hello	Hello
add some	special \| characters	like Pipe

If you want to be able to show code on your site (3 ticks) You can also add Syntax Highlights. Just add the code name after the ticks

{
    'firstName':'James';
    'lastName':'Smith';
    'age': 30;
}

Subscripts X₂

Internal Linking... - Go to Markdown

Adventures in Images¶

I had a major learning opportunity when I started trying to get my images to appear on the webpages that I pushed to the site.

So I thought my images weren't showing up because my docs folder was outside of the public folder on my repository. So I moved my docs folder and everything else into the public folder. And then started to try to revise the yml file so that it would point there.

Then it just wasn't working - and I still couldn't see the image. I asked Kenny Hu for help. He showed me how to see the build pipeline on the Gitlab site. He said, “Look, this is failing, so something's going on here."

Relative

NEXT TRY - Dug deeper and started to ask Claude for help about how to make the site build again. How to revise my yml so that it would read documents in public. DISCOVERY - then I found out that actually that wasn't ever working. I asked Claude, hey, I moved everything into public. He said, oh no public is not where you publish files. It gets rewritten every time I'll post what Claude said.

The public/ folder is only for the final built/generated website that GitLab Pages will serve. It's the output, not the source.

I learned that the public file gets rebuilt every time and actually docs should be outside of it. So that wasn't the problem with my images, so I'm going to now learn how to use revert and get and go back to before I moved all those documents into the public file, which is great, another learning opportunity.

NEXT TRY using the git revert + #COMMIT_HASH to get back to my files before I tried moving them into the PUBLIC folder

However, that didn't work

camil@DESKTOP-CQDH3O8 MINGW64 ~/FAB_ACADEMY/camille-kanofsky (main)
 $ git revert 5d1e26c
Auto-merging public/docs/index.md
CONFLICT (content): Merge conflict in public/docs/index.md
error: could not revert 5d1e26c... made he cat smaller with html
hint: After resolving the conflicts, mark them with
hint: "git add/rm <pathspec>", then run
hint: "git revert --continue".
hint: You can instead skip this commit with "git revert --skip".
hint: To abort and get back to the state before "git revert",
hint: run "git revert --abort".
hint: Disable this message with "git config advice.mergeConflict false"
camil@DESKTOP-CQDH3O8 MINGW64 ~/FAB_ACADEMY/camille-kanofsky (main|REVERTING)

LEARNING MOMENT - git revert --abort

camil@DESKTOP-CQDH3O8 MINGW64 ~/FAB_ACADEMY/camille-kanofsky (main|REVERTING)
$git revert --abort

NO SPACE AFTER THE “$” even though it put a space in by default

Then I manually moved the files back and the pipeline was repaired.

Relative

Then with Kenny’s help, I crafted a prompt to help me learn about where to put my images so they would build with my pages. The prompt was “in the context of gitlab pages how are public assets handled? where are my images and how do I point to them”

How to Reference Images in Markdown From the same folder:

'![Description](photo.jpg)'

From an images subfolder:


 '![My photo](images/photo1.jpg)'

 '![Diagram](images/diagram.png)'

From a different page:


<!-- In docs/week1/assignment.md -->

![Logo](../images/logo.png)

When MkDocs builds your site (mkdocs build --site-dir public), it:

Copies all files from docs/ to public/

Converts .md files to .html

Preserves your images and folder structure

Updates all image paths automatically

Best Practices

Create an images/ folder inside docs/

Use relative paths in your Markdown

Don't put images in the root - keep them in docs/

Commit images to Git - they're part of your documentation

I was able to follow these suggestions and recommit my files and now all is working well.

More Image Errors¶

More work with Claude to get my images to show up on my about.md page.

I kept getting the following error:

WARNING - [22:22:29] "GET /about/images2/family.jpg HTTP/1.1" code 404

Claudes Help:

MkDocs is adding /about/ because of how your site is being built! The issue: When MkDocs builds your site, about.md becomes about/index.html, so the URL is yoursite.com/about/. When the browser sees a relative path like images2/family.jpg, it looks relative to the current page's directory, which is /about/.

Solution - use an absolute path from site root:
<img src="/images2/family.jpg" style="width: 50%;">

Or in markdown:
![Family](/images2/family.jpg)

The leading / tells MkDocs to look from the site root (the docs/ folder), not relative to the current page.

Why this happens: * about.md → becomes /about/ (a directory) * Relative path images2/family.jpg → browser looks for /about/images2/family.jpg * Absolute path /images2/family.jpg → browser looks for /images2/family.jpg ✓

Try this in your about.md: <img src="/images2/family.jpg" alt="Family" style="width: 50%;">

Jeckyll¶

I also played with making a Jeckyll site on my personal github.

I used this minimal mistakes template, and a whole lot of Claude. I used the readme file and the links with in it, including the jeckyll site to make the site.

In the end, I decided to go with the mkdocs becuase it seemed simpler to use and pretty efficient. I was able to integrate the HTML easily which I like.

These are just some of my goals for this week that I think will help me to be ready to document more efficiently ↩