I'm part of a community of self-taught developers. I'm trying to help tech newbies in the discord channel.
Judging from the number of questions, new developers seem to have problems deploying static websites to GitHub pages.
In this article, I'll show you a basic way to bring your first front-end projects to life on GitHub pages.
Prerequisites
On your computer:
You'll also need a free GitHub account.
Create a new project
You'll need something that you want to upload to the internet: a HTML page, optionally with CSS and JavaScript.
You can either use your own project or you can follow along and make a dummy project.
- Create a new folder on your computer.
I'll show you the example commands for Unix. Windows commands might be different, so be aware.
mkdir my-github-project
cd my-github-project
- Initialize Git.
GitHub works with Git. We need to initialize the project.
# replace with your name!
git config --user.name "Mona Lisa"
# use the email you used for signing up for a GitHub account
git config --user.email "monalisa@example.com"
git init
Now we'll add a special .gitignore file with the following content:
node_modules
.gitignore
- Create files.
The minimum is a HTML file called index.html. But let's also create a JavaScript and a CSS file.
First, we need to put everything into a folder called dist, as that's the folder that will be deployed to GitHub pages. You can choose the name freely, but dist is a common one.
If you change the name, you'll also need to change it later in step 4.
Command-line commands (in your terminal):
mkdir dist && cd dist
mkdir css
mkdir js
touch index.html
touch css/styles.css
touch js/scripts.js
The file structure looks like so:
.
├── dist
│ ├── css
│ │ └── styles.css
│ ├── index.html
│ └── js
│ └── scripts.js
└── .gitignore
Put the following content inside index.html:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>The HTML5 Herald</title>
<meta name="description" content="The HTML5 Herald" />
<meta name="author" content="SitePoint" />
<link rel="stylesheet" href="css/styles.css?v=1.0" />
</head>
<h1>Hello World</h1>
<body>
<script src="js/scripts.js"></script>
</body>
</html>
As you can see, the file references a JavaScript script and a CSS file. We should add them, too.
Content of js/scripts.js:
console.log('Hello, world')
Content of cs/styles.css: The content of the CSS file will be a modern CSS reset, which makes a good base template for your project.
/* Box sizing rules */
*,
*::before,
*::after {
box-sizing: border-box;
}
/* Remove default margin */
body,
h1,
h2,
h3,
h4,
p,
figure,
blockquote,
dl,
dd {
margin: 0;
}
/* Remove list styles on ul, ol elements with a list role, which suggests default styling will be removed */
ul[role='list'],
ol[role='list'] {
list-style: none;
}
/* Set core root defaults */
html:focus-within {
scroll-behavior: smooth;
}
/* Set core body defaults */
body {
min-height: 100vh;
text-rendering: optimizeSpeed;
line-height: 1.5;
}
/* A elements that don't have a class get default styles */
a:not([class]) {
text-decoration-skip-ink: auto;
}
/* Make images easier to work with */
img,
picture {
max-width: 100%;
display: block;
}
/* Inherit fonts for inputs and buttons */
input,
button,
textarea,
select {
font: inherit;
}
/* Remove all animations and transitions for people that prefer not to see them */
@media (prefers-reduced-motion: reduce) {
html:focus-within {
scroll-behavior: auto;
}
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}
- Install npm package
Now we'll need to install the Node.js package gh-pages, which will help us to bring the site to GitHub.
First, initialize a new npm project in the root project folder (the parent folder of the dist directory).
npm init -y
Now install the package:
npm install -D gh-pages
You'll now see a new folder called node_modules and also a new file called package.json.
Adjust package.json:
// previous code
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
"deploy": "gh-pages -d dist" // NEW
},
// more code
(Remember to change the name of the dist folder if you previously used a different name.)
- Create GitHub project.
Go to https://github.com/new with your web browser and create a new repository.
The name should be your project name, in this example it's my-github-project. You can make the project public or private, it does not matter. Leave the rest of the check-boxes unchecked.
You can find a step-by-step guide on the GitHub help pages.
- Commit and upload your files.
Now we need to connect the files on your local computer with the remote repository (GitHub).
Follow the guide.
In you terminal:
git remote add origin https://<your-github-name>/<your-github-repository-name>.git
Replace <your-github-name> and <your-github-repository-name> with the correct values for your project.
Now we are ready to upload everything to the internet!
In you terminal:
git add . # add everything to the staging area
git commit -m "Initial Commit" # add a commit message
git push origin master
# origin is the name of the remote repository
# master is the name of the git branch
If you navigate to your GitHub project in your web browser, you should see that all your files are online now.
- Deploy to gh-pages via script.
The final step is to run the npm script (see package.json):
npm run deploy
FAQ
What if I have several projects in my folder?
You should make separate GitHub repositories. Repeat the steps of this blog post for each. Repositories on GitHub are free.
Final Words
Using Git, GitHub pages and Npm is not an easy feat for a beginner.
Brad Traversy has a YouTube video about deployment to GitHub pages. He also shows you to setup a domain:
Links
- GitHub Pages Deploy & Domain by Brad Traversy
- HTML5 Template: A Basic Boilerplate for Any Project by Louis Lazaris
- A modern CSS reset by Andy Bell
Top comments (0)