DEV Community

Cover image for Deploy to GitHub Pages Without Jekyll
Sophia Brandt
Sophia Brandt

Posted on • Originally published at on

Deploy to GitHub Pages Without Jekyll

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.


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.

  1. 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
Enter fullscreen mode Exit fullscreen mode
  1. Initialize Git.

GitHub works with Git. We need to initialize the project.

   # replace with your name!
   git config "Mona Lisa"
   # use the email you used for signing up for a GitHub account
   git config ""
   git init
Enter fullscreen mode Exit fullscreen mode

Now we'll add a special .gitignore file with the following content:

Enter fullscreen mode Exit fullscreen mode
  1. 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
Enter fullscreen mode Exit fullscreen mode

The file structure looks like so:

    ├── dist
    │   ├── css
    │   │   └── styles.css
    │   ├── index.html
    │   └── js
    │       └── scripts.js
    └── .gitignore
Enter fullscreen mode Exit fullscreen mode

Put the following content inside index.html:

   <!DOCTYPE html>

   <html lang="en">
       <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" />

     <h1>Hello World</h1>

       <script src="js/scripts.js"></script>
Enter fullscreen mode Exit fullscreen mode

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')
Enter fullscreen mode Exit fullscreen mode

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 */
   *::after {
     box-sizing: border-box;

   /* Remove default margin */
   dd {
     margin: 0;

   /* Remove list styles on ul, ol elements with a list role, which suggests default styling will be removed */
   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 */
   picture {
     max-width: 100%;
     display: block;

   /* Inherit fonts for inputs and buttons */
   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;
     *::after {
       animation-duration: 0.01ms !important;
       animation-iteration-count: 1 !important;
       transition-duration: 0.01ms !important;
       scroll-behavior: auto !important;
Enter fullscreen mode Exit fullscreen mode
  1. 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
Enter fullscreen mode Exit fullscreen mode

Now install the package:

   npm install -D gh-pages
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

(Remember to change the name of the dist folder if you previously used a different name.)

  1. Create GitHub project.

Go to 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.

  1. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

If you navigate to your GitHub project in your web browser, you should see that all your files are online now.

  1. Deploy to gh-pages via script.

The final step is to run the npm script (see package.json):

   npm run deploy
Enter fullscreen mode Exit fullscreen mode


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:
GitHub Pages Deploy & Domain


Top comments (0)