Saltar a contenido

Project Management

Using repositories correctly can be challenging at first for those unfamiliar with the platform. Using them to document processes and publish information on a personal website makes it a powerful tool to move forward and explore new possibilities when the right tools are combined.

Tools

Git
GIT
Version Control & Collaboration
CSS
CSS
Web Styling & Visual Design
HTML
HTML
Web Structure & Markup
MkDocs
MkDocs
Static Site Generation & Documentation

Setup

1. Within the project structure, you will need to work with a GitLab repository:

First create your repository where you will host your files and install Git + Python + MkDocs which work together.

2. Configure your Git environment

$ git config --global user.name "Username"
$ git config --global user.email "speedy@mail.com"

3. Generate your SSH key

Verify 

$ cat ~/.ssh/id_rsa.pub

Generate 

$ ssh-keygen -t rsa -C "your_email@example.com"

Confirm

$ cat ~/.ssh/id_rsa.pub

Copy

$ clip < ~/.ssh/id_rsa.pub

4. Paste your SSH key into your GitLab repository

5. Upload your repository to GitLab (online)

Add the base documents you will work with

$ git add index.html
$ git add .

Download the latest version of your repository or your most recent copy

$ git pull

Now tell Git to provide you with a functional copy of your repository

$ git merge

Now, create a Commit describing the changes you have made. This also serves as a reference in case you need to track or review your modifications later.

$ git commit -m "changes i did"

Upload your changes to the repository

$ git push

Cheat sheet for Git

$ git config --global user.name "Joe Smith" ; sets the name used for all commits
$ git config --global user.email "jSmith@mail.com" ; sets the email used for all commits
$ git config --global credential.helper osxkeychain ; stores credentials securely (macOS)
$ git config --list ; shows current git configuration
$ git config --global core.editor "nameOfTextEditor -wl1" ; sets default editor
$ git config --global color.ui true ; enables colored output
$ cat .gitconfig ; displays git config file

Local Git

$ git init ; initializes a new git repository
$ ls -a ; lists all files including hidden ones
$ git status ; shows repository status
$ git add filename ; stages a specific file
$ git commit -m "commit message" ; saves changes to history
$ git log ; shows commit history

Remote Repository

$ git remote add origin https://github.com/user/repo.git ; links local repo to remote
$ git push -u origin master ; pushes commits and sets upstream
$ git pull ; fetches and merges remote changes
$ git fetch ; downloads remote changes only
$ git merge ; merges fetched changes

File management

$ git add . ; stages all modified files
$ git add *.html ; stages all html files
$ git commit -am "commit message" ; stages and commits tracked files

Undo and reset

$ git checkout -- filename ; discards local file changes
$ git reset HEAD filename ; removes file from staging
$ git commit --amend ; edits last commit

Branches

$ git branch ; lists branches
$ git checkout -b branch-name ; creates and switches branch
$ git branch -d branch-name ; deletes branch

Stash

$ git stash save "message" ; temporarily stores changes
$ git stash pop ; restores and removes last stash
$ git stash clear ; deletes all stashed changes

MKDocs

Now that the repository is linked, we will create a local repository. This allows you to manage your project locally on your PC.

1. Create the your-project folder with an mkdocs.yml file

$ mkdocs new mi-proyecto; creates a new MkDocs project structure
$ cd ~ /Desktop/antonio-quintal ; moves you into the project directory

It is important to mention that this syntax is used in Git.

2. Initialize your repository locally.

$ git init ; initializes a new Git repository
$ git add . ; stages all files in the project
$ git commit -m "Inicio: sitio MkDocs" ; creates the first commit of the MkDocs site

3. Connect your local repository to the main branch.

$ git init ; initializes a new Git repository
$ git add . ; stages all files in the project
$ git commit -m "Inicio: sitio MkDocs" ; creates the first commit of the MkDocs site
$ git remote add origin git@gitlab.com:usuario/mi-proyecto.git ; links the local repository to the remote GitLab repository
$ git push -u origin main ; pushes the main branch and sets it as upstream

4. Configure your MkDocs properties


site_name: "Antonio Quintal - Fab Academy 2026"
site_url: "https://gitlab.fabcloud.org/academany/fabacademy/2026/labs/ciudadmexico/students/antonio-quintal/"
use_directory_urls: true

site_description: "Documentation"
site_author: "Antonio Quintal Ricardez"
copyright: "Copyright 2026 Antonio Quintal - Creative Commons Attribution Non Commercial"

theme:
  name: material
  language: es
  logo: images/rubik.png
  favicon: images/rubik.png
  palette:
    primary: green
    accent: light-green
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - search.suggest
    - search.highlight

nav:
  - Home: index.md
  - About: about.md
  - Project: project.md
  - Assignments:
      - Week 01 — Project Management: assignments/week01.md
      - Week 02 — CAD: assignments/week02.md

plugins:
  - search
  - git-revision-date-localized:
      fallback_to_build_date: true
      enabled: !ENV [ENABLED_GIT_REVISION_DATE, False]

markdown_extensions:
  - md_in_html
  - pymdownx.superfences
  - pymdownx.highlight:
      pygments_style: github-dark

extra_css:
  - stylesheets/extra.css

extra:
  social:
    - icon: fontawesome/brands/instagram
      link: "https://instagram.com/fabacademany"

3. Generate a local server

On this server, you can preview the site locally before uploading it in order to confirm your changes

$ mkdocs serve ; starts a local development server to preview the site
$ mkdocs build ; builds the static site into the site/ directory

4. Publish your repository

Run this process every time you update your content

$ py -m mkdocs build --clean --site-dir public ; builds the site and outputs it to the public directory

Finally, GitLab will automatically start building your page. This process removes the old content and generates the new version inside the public/ directory

$ git add . ; stages all updated files
$ git commit -m "Update documentation" ; saves documentation updates
$ git push ; pushes changes to the remote repository

HTML and CSS

It´s the markup language used to structure a web page and CSS It´s the language used to visually style that structure, including colors, sizes, borders, shadows, margins, and fonts.


$ .md-header {
> background-color: #2f4f2f; military green header
$ }

$ .md-tabs {
> background-color: #2f4f2f; navigation tabs
$ }

$ .md-tabs__link {
> color: #e6efe6;
> font-weight: 600; tab text
$ }

$ .md-tabs__link--active {
> color: #ffffff;
> border-bottom: 2px solid #9fbf9f; active tab
$ }

$ pre.term {
> background: linear-gradient(180deg, #0d1117, #0b1016);
> border-radius: 10px;
> box-shadow: 0 6px 18px rgba(0,0,0,0.35); terminal block style
$ }

$ pre.term .bin {
> color: #79c0ff; commands (git, mkdocs)
$ }

$ pre.term .pkg {
> color: #ffa657; values / packages
$ }

Errors

It is very common to make mistakes during the process; however, the most common issues have been addressed in this guide in case you encounter the same ones:

Local server not displaying content in the repository

  • Make sure you have added your images using git add.
  • GitLab Pages may serve content from a subdirectory. Check the site_url value in mkdocs.yml if you are using a custom domain or a base path.

Errors in mkdocs.yml

  • YAML is sensitive to spacing. Incorrect indentation or invalid characters will cause MkDocs to fail. The error message shown when running mkdocs build usually indicates the problematic line.
  • If you see new files (images or .md files) listed as untracked, run git add. A common mistake is not uploading the docs/images folder, which causes images not to appear on the website.

CRLF warnings
On Windows, Git may display warnings such as LF will be replaced by CRLF. This is normal when saving files on Windows, and Git handles it automatically. If necessary, it can be disabled using git config core.autocrlf or git config core.safecrlf, but it does not prevent the site from building.

site/ or public/ folders in the repository

  • Do not manually upload the public/ or site/ folders to the repository.
  • GitLab automatically generates the public/ folder during each pipeline execution.

Incomplete push or forgotten commits:
After each change, make sure to commit and push your updates.

Incorrect paths
Using /images/Photo.png instead of images/Photo.png.

Duplicate folders
Sometimes two docs or public folders are created unintentionally.

Unsaved changes
Make sure the file is saved before committing. Using git diff helps verify which changes are actually being uploaded.