Create the Repository
Every project starts with a repository: a folder versioned with Git and stored on GitHub. You can create it in two ways: through the GitHub website (by clicking) or in the terminal (by typing). Both get you to the same place. Let's look at both.
🧠 Analogy: The Repository Is a Labeled Drawer
Imagine a drawer with your project’s name on the front. Everything that belongs to the website goes in it: the files, the version history, the labels. GitHub is the cabinet full of these drawers, in the cloud. Creating the repository is just opening a new drawer and putting on the label with its name.
👁 Path A: through the GitHub website
- •Go to github.com logged in and click the green button New (or in the + at the top right > New repository).
- •In Repository name, type
minha-landing(no spaces, no accents). - •Leave it as Public (needs to be public for Pages to work on the free plan).
- •Select Add a README file and click Create repository.
Path B: through the terminal
If you have the gh (GitHub CLI) installed, you can create everything at once. Otherwise, you can use plain Git and connect it afterward.
# Option 1: with GitHub CLI (creates local + remote all at once)
$ gh repo create my-landing --public --clone
Created repository seu-usuario/minha-landing on GitHub
# Option 2: Git only, create a folder and initialize the repository
$ mkdir minha-landing
$ cd minha-landing
$ git init
Initialized empty Git repository in .../minha-landing/.git/
# after creating the empty repo on the site, connect the remote
$ git remote add origin https://github.com/your-username/my-landing.git
Project folder structure
For a simple landing page, you only need three things: the page, the style, and a folder for images. Clean and straightforward.
minha-landing/
├── index.html
├── style.css
├── README.md
└── img/
└── foto.jpg
⚠️ Common Error
Problem: created the repository as Private and GitHub Pages won’t publish.
Solution: on the free plan, Pages only works with a public repository. Go to Settings > General > Danger Zone > Change visibility and change it to Public. Or create a new repository as Public from the start.
Basic HTML: The Minimum You Need to Get It Working
HTML is the structure of the page: headings, paragraphs, images, links. Each piece goes inside a tag, which opens with <tag> and closes with </tag>. You don't need to memorize everything. With just a handful of tags, you can build a working page.
🧠 Analogy: Tags Are Boxes That Fit Together
Think of boxes inside boxes. The box <html> stores the entire page. Inside it there's the box <head> (information the browser reads) and the box <body> (what appears on the screen). Every box you open, you need to close.
A index.html complete and simple
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<title>My Site</title>
</head>
<body>
<h1>Hello, I'm João</h1>
<p>Welcome to my first page.</p>
<img src="img/foto.jpg" alt="My photo">
<a href="https://inema.club">My link</a>
</body>
</html>
What each tag is for
- •
<!DOCTYPE html>indicates that it's a modern HTML page. - •
<head>stores the title and settings (doesn't appear on screen). - •
<title>is the name that appears in the browser tab. - •
<body>is everything that appears on the screen. - •
<h1>is the large title;<p>is a paragraph of text. - •
<img>shows image;<a>creates a clickable link.
💡 Tip: test by opening the file
Before publishing, open the index.html directly in the browser (double-click the file or run open index.html on Mac, xdg-open index.html on Linux). If it looks right on your computer, it will look right when it's live.
⚠️ Common Error
Problem: the image doesn't appear, just a broken square.
Solution: the path in src needs to match the file's actual location. If the photo is in img/foto.jpg, type exactly this. Capitalization matters: Foto.JPG and is different from foto.jpg on the server.
Basic CSS: Make It Presentable
If the HTML is the structure, the CSS and the appearance: colors, fonts, spacing, alignment. You write the style in a file style.css and connects it to the HTML with one line. Done: the same page goes from a "dull document" to a polished landing page.
🧠 Analogy: CSS is the page’s outfit
HTML is the body: head, torso, arms. CSS is the clothing you wear on that body: the color, the size, the fit. The same HTML can use a thousand different styles, just as you can change clothes without changing your body.
Step 1: connect the style.css to the HTML
Inside the <head> of yours index.html, add this line:
<link rel="stylesheet" href="style.css">
Step 2: one style.css for example
/* background color and font for the entire page */
body {
background-color: #0f172a;
color: #e2e8f0;
font-family: Arial, sans-serif;
text-align: center;
max-width: 600px;
margin: 40px auto;
}
/* large green title */
h1 { color: #10b981; }
/* round photo */
img { border-radius: 50%; width: 160px; }
👁 How to read a selector
Each CSS block has three parts:
- •Selector (
h1): who to apply it to. - •Property (
color): what to change. - •Value (
#10b981): the new value. End with;.
The trick margin: 40px auto with max-width is the classic way to center the content on the screen.
✓ What TO DO
- ✓Keep the CSS in a separate file (
style.css) - ✓Use only a few colors and one font
- ✓Close each block with
}
✗ What NOT to do
- ✗Forget the
;at the end of each line - ✗Get the filename wrong in the
href - ✗Fill the page with garish colors
Publish on GitHub Pages
This is the magic part: the GitHub Pages takes the files from your repository and serves them as a real website, for free, with a public URL. There are three steps: upload the files (commit + push), turn on Pages, and see it live.
Commit and push the files
Send your machine's code to GitHub.
$ git add .
$ git commit -m "first version of the landing page"
[main 1a2b3c4] first version of the landing page
$ git push -u origin main
To github.com:seu-usuario/minha-landing.git
Enable Pages
In the repository, go to Settings > Pages.
- •In Source, choose Deploy from a branch.
- •In Branch, select
mainand the folder/ (root). - •Click Save.
Wait and see it live
In 1 to 2 minutes, GitHub publishes it and displays the URL.
# the final URL looks like this:
https://seu-usuario.github.io/minha-landing/
👁 What you’ll see on the screen
After saving, the Pages page itself shows a green box:
✓ Your site is live at
https://seu-usuario.github.io/minha-landing/
# Visit site
Click Visit site and see your landing page live. This address is public: you can send it to anyone.
⚠️ Common Error
Problem: opened the URL and a page appeared 404.
Solution: it’s usually because the file isn’t named index.html (Pages looks for this name), or you’re still in the first few seconds of publishing. Check the file name, wait 1-2 minutes, and refresh the page with Ctrl+F5.
Custom Domain
OPTIONAL
The URL seu-usuario.github.io already works perfectly. But if you want your own address, like meunome.com.br, you can connect a custom domain. This is optional and costs the price of the domain (a few reais per year). Skip this topic if you don't want to spend money yet.
🧠 Analogy: A Domain Is a Nice-Looking Address
GitHub gives you an address that works but is long. A domain is like changing "Rua 3, Quadra 12, Lote 4" to "Casa do Joao." The place is the same; only the name is easier to remember and share.
Buy the domain
At a registrar (Registro.br for .com.br, or Namecheap, Cloudflare, Google Domains for others). Choose the name and pay the annual fee.
Point DNS to GitHub
In the registrar’s dashboard, create a record CNAME pointing your domain to the GitHub address.
# Type Name Value
CNAME www seu-usuario.github.io
Register the domain on GitHub
In Settings > Pages > Custom domain, enter your domain (e.g., www.meunome.com.br) and click Save. Check Enforce HTTPS when it becomes available.
Wait for DNS to propagate
DNS changes take anywhere from a few minutes to 24 hours to take effect worldwide. Be patient: it's not an error, just propagation time.
💡 Tip: start without a domain
You don't need to buy a domain to complete this project. The URL github.io already counts as a "live site." Your own domain is an upgrade you can make whenever you want a more professional-looking address.
Final Exercise: Your Landing Page Live
Now you do everything together, from scratch to the public URL. Follow the checklist in order. When you finish, you’ll have a real website on the internet, built by you, with its own address to share.
🎯 What you'll build
A personal landing page: a title with your name, an introductory paragraph, a photo, and a link. Versioned with Git and published on GitHub Pages.
Step 1: create the folder and files
$ mkdir minha-landing
$ cd minha-landing
$ touch index.html style.css
$ mkdir img
Step 2: write the HTML and CSS
Open it in the editor and paste the contents of topics 2 and 3.
$ code .
# write index.html and style.css, then save
Step 3: Initialize Git and make the first commit
$ git init
$ git add .
$ git commit -m "my personal landing page"
[main (root-commit) 1a2b3c4] my personal landing page
Step 4: Connect to GitHub and push
# create the repo on the site (Public) and copy the URL, then:
$ git remote add origin https://github.com/your-username/my-landing.git
$ git push -u origin main
Step 5: Enable GitHub Pages
- •Settings > Pages > Source: Deploy from a branch.
- •Branch
main, folder/ (root), Save.
Step 6: Open the public URL
# wait 1-2 min and open:
https://seu-usuario.github.io/minha-landing/
If your landing page appears at this address, is live. Mission accomplished.
✓ Make sure you have
- ✓Public repository on GitHub
- ✓
index.htmlestyle.csscommitted - ✓Pages enabled on the branch
main - ✓Public URL opening your page
✗ If it doesn't work, check
- ✗Repo is Private (needs to be Public)
- ✗The file isn’t called
index.html - ✗Forgot the
git push - ✗Didn't wait for the deployment to finish
🏆 Congratulations, you've completed Track 1!
You started from scratch and put a website online using the terminal, Git, GitHub, and GitHub Pages. That’s exactly the path professionals take every day. In the Track 2, you’ll level up with modern deployment: Vercel, a cloud database, APIs, and environment variables.
📚 Module Summary
Next Track:
Track 2 - Modern Deploy (Vercel, Supabase, APIs, and environment variables). You’ll finish Track 1 with a live website and move on to deploying real applications.