Create gh-pages branch in existing repo
It’s easy to serve a website using GitHub Pages by creating the gh-pages branch in a GitHub repo. The instructions can be found here.
In my case, I have an existing repository that has some stuff. I want to use GitHub Pages to serve some .md files, but I don’t want to include the stuff from my master branch. What I had to do was:
- Create/checkout an orphan gh-pages branch.
- An orphan branch is not connected to the other branches and commits, and its working tree has no files at all. See here for more info.
- Commit .md files to the branch.
To create the orphan gh-pages branch (based on instructions from Hugo):
Once the branch is pushed to GitHub, you have to go to the Settings page of the repository. In the section “GitHub Pages”, select gh-pages as the source. The step is described in more details here. If successful, you will see a message saying “Your site is published at https://your-username.github.io/your-repository/”.
Now you can add files to the gh-pages branch, and they will show up on your new website:
Deploying React app on Github (Master or gh-pages branch)
Recently, I tried to deploy my personal website on github under the link https://<username>.github.io, though people have been publishing their static sites on github page but I was having a hard time deploying my React app.
Actually, it’s pretty simple and if done correctly and hardly takes 5 mins.
First we will see how to deploy a React app on master Branch because to publish under url “https://<username>.github.io”, deployment should be done on master branch.
- Create your react app.
- Make a github repository with the name “<username>.github.io”, initialise it with readme so that the master branch is created. For example, I have created with “pragyak412.github.io”.(replace it with your username in all the following steps).
- In your react app, initialise git and set remote origin to the repository created. After taking pull from repository, make a development branch to push your UI code(not necessary) as master branch will be used for deployment.
- Remove readme from master branch and make sure it is empty, also you can set you default branch to dev branch by going to Settings>>Branches.
- Now in your react app, install gh-pages and edit your package.json by adding these.
- Now you are all set to deploy your website by using the following command.
To check deployment, click on Environment:
Now next we will see how to publish react app under url “https://<username>.github.io/<repository-name>” , for this deployment can be done on any branch. In Settings>>Sources of github, option is given to select the branch for the same.
- Create your react app.
- Make a repository on github, you can name it anything(In my case , I have made my_app repository, make sure you add your repository name in following steps).
- In your react app, initialise git and set remote origin to the repository created (as shown in previous).
- Install gh-pages, and edit your package.json. Here while editing no need to add master for deploy and hence there is small change in than shown previously.
- Now your react app is ready for deployment.
Now a new branch will be created in your github repository named gh-pages, and you can check the deployment status on the Environment .
While publishing your repository in this case, you get the option to select the branch in Settings>>Source.
Tutorial: How to set up and automatically deploy your website to GitHub Pages
So you want to host your static website on GitHub Pages? Excellent choice! In this tutorial, I’m taking you through the steps to host your static website on GitHub Pages and how you can deploy your own changes. After this tutorial, you will be able to automatically deploy your own website to the internet. Before we get into the steps you have to take to publish your website to GitHub Pages, I will outline a few options and limitations you have when using GitHub Pages for your website hosting.
What are my options for hosting a static website?
There are a few options you have for hosting your website on GitHub Pages, these include:
- Using Jekyll to generate your website
- Using your master branch as your source and production website
- Using your master branch as your source and gh-pages as your production website
In this post, I will not be going over how to use Jekyll in combination with GitHub pages. Jekyll is supported by GitHub, which means GitHub will do everything needed to deploy a Jekyll website for you. In this tutorial, we’ll focus on deploying a plain HTML / CSS / JavaScript website.
The second option is to use the master branch both as the source of your website and the production website itself. What this means is that all of your source files, including build scripts, package.json file, and other «source» files like SCSS are accessible through the internet. For example, you’d be able to see the contents of your SCSS files by going to https://yourwebsite.com/scss/_header.scss. This is the easiest solution for hosting your website on GitHub Pages, but it’s not the cleanest option.
This is where the third option comes in: using your master branch for all your source files and having a separate «gh-pages» branch that holds the production files for your website. This is a slightly more involved solution but is much cleaner than the second option. This is what this tutorial will focus on.
What are the limitations of hosting on GitHub Pages?
Hosting on GitHub Pages is great, but there are some limitations and gotchas. These include:
- You can only host static websites (or dynamic through static JS files)
- Your repository is the source of truth, so your compiled JS / CSS files need to be in Git
GitHub Pages is essentially a service that gives you a folder on a server. A web server like Nginx is serving the files as-is. There is no scripting layer and you can’t execute PHP files for example. If you want to have a dynamic website, you can still do this, but you’ll need to do it through JavaScript. JavaScript files are static files, so the server will be able to serve those as they are. When the files have been served, it’s possible to retrieve data from any external service you have at your disposal.
Another thing that seems a little backward, if you’ve worked with CI/CD systems before, is that all of your production files will need to be in Git. Normally you only have your source files in Git, because the CI/CD pipelines build the production files for you. With GitHub Pages, you could accomplish this by using GitHub Actions, but we’ll keep this tutorial simple and not go over that.
Setting up your GitHub Pages environment
Enough talk, let’s get our hands dirty and set up our GitHub Pages environment with all the automation you need to quickly deploy new changes to your website.
Step 1: Create / Update your GitHub repository to be public
GitHub Pages can be done on private repositories, but for this tutorial, we’ll focus on using a public repository for your website. The only difference between using private and public repositories for this is that you need to have a pro membership in order to use private repositories. If you already have this, you can skip to step 2 and follow along from there.
If this will be a new project for you and you still need to create a repository for your website, make sure to select the public option like displayed below:
If you already have a repository, but it’s a private repository, you can make it public by clicking «Settings» and scrolling down to the danger zone:
Click on «Make public» and you’re ready for the next step.
Step 2: Create a website on your master branch
This is a step that’s completely up to you. The aim of this step is to create some kind of content that can be displayed in the browser. You can make an entire static website or just create something simple and move on to the next step. For the sake of simplicity, I will only add an H1 to my project:
Step 3: Enable GitHub Pages on your repository
Before we enable GitHub Pages on this repository, you have to make a choice about which option you want to use for hosting your website on GitHub Pages. For the sake of this tutorial, I will use the third option: Using «master» as the source branch and «gh-pages» as the production version of the website.
To create the «gh-pages» branch, click on «Branch: master» and type gh-pages like below:
Then press: «Create branch: gh-pages from master». You will now have two branches in your repository: master and gh-pages. To enable GitHub Pages on your repository, click on «Settings» and scroll down the «GitHub Pages» section. You should see something like this:
As you can see, GitHub has already enabled this repository for GitHub Pages, because it detected the «gh-pages» branch. If you chose to stick with the master branch, you will have to enable GitHub pages here and select the master branch as the source.
Now when we visit the url displayed in the blue header, you will see your website:
Step 4: Using a custom domain
Your website is now located at https://your-username.github.io/repository-name. But oftentimes you want your website to be at a domain you already own. To do this, first, you’ll need to decide which type of URL you want to use for this. You can choose a main (apex) domain or a subdomain for this.
Step 4A: Using the main domain as your custom domain
If you want to use the main domain (roelofjanelsinga.com) then you’ll need to create a few new DNS records in the service where you manage your domains. This is what my DNS records look like:
All you need to do here is create 4 A-records for your main domain and point them to the IP addresses below:
You can set the TTL to whatever you like, in my case I set them to 1 hour.
Step 4B: Using a subdomain as your custom domain
Using a subdomain is much easier than using the main domain as your custom domain. You will still need to change your DNS records, but this time you’ll only need to do this:
You create a CNAME-record for the subdomain you want to use, for example, amazing.yourwebsite.com. Set the TTL to whatever you want, I use 1 hour for this. Then the content of your CNAME should be your-github-username.github.io, in my case roelofjan-elsinga.github.io.
Step 4C: Submitting your custom domain to GitHub
Now that you’ve set up your DNS records, you can submit your custom domain to GitHub. In the «Custom domain» field you can now enter whichever main domain or subdomain you chose and press «Save». A new file called «CNAME» will now appear in your repository. This will contain the domain you chose.
When using a custom domain, you might have to re-enable «Enforce HTTPS» for your website. It might take a while before this option becomes available because GitHub will verify your DNS settings. It might still give you warnings that your DNS settings are incorrect, but you can ignore these warnings if you followed the previous steps. This will automatically go away as soon as GitHub sees your updated DNS records. After a little while, you will be able to see your website appear on the domain you’ve chosen.
If you’ve already set up build scripts and your workflow is to your liking, this could be the last step you need to follow in this tutorial. Step 5 and 6 are about automating your build process and your deployments. These are nice to have, but they’re not necessary to use GitHub Pages in any way.
Step 5: Automate your build process
If your deployment process becomes more difficult by using GitHub Pages, there is really no reason you should do it. This is why I’m including some scripts that you can use to automate your build and deployment processes. I make the following assumptions for these steps, as I can’t cover every scenario out there:
- You’re using a build command (gulp build, npm run prod, etc.) to compile production assets
- Your production branch is gh-pages and your source branch is master
- You’re using a «dist» folder that contains all production assets after running your build command
I’m more than happy to help you out if your situation is different than the assumptions I’m making here, just contact me on Twitter and I’ll help you out with this step.
To be able to make everything automatic, I’m going to include an NPM package called Husky. Husky is a tool for NPM that enables you to define git hooks right inside of your package.json file. Git hooks are essentially events that are triggered when you interact with Git. For example, when you commit a change, the events pre-commit and post-commit are emitted. Husky allows us to listen for those events and perform certain tasks. For this tutorial we only need pre-commit, so let’s set that up. First, let’s install husky:
Now, in our package.json file, include the following configuration:
Now, every time we commit a change in Git, «npm run prod» will be executed. You can replace this with your own build script, for example: «gulp build» or «webpack». In the case of my simplistic project, this could mean that we copy the index.html file to dist/index.html.
One last thing that we need to do is add new scripts to your package.json:
The «postinstall» script executes after you run «npm install». This makes sure that husky runs properly. I recommend you run «npm run postinstall» to be certain that husky has done what it needs to do. The deploy command will be needed in the next step, so just copy and paste it for now.
Now our code will be built every time we commit a change, without having to think about it. Just how we like it.
Step 6: Automate your deployment process
We’ve already automated the build process, so now we can automate the deployment process. For this, we’re going to make use of GitHub Actions. This sounds very intimidating, but I’ll explain exactly what’s going on and I’ll give you the configuration you need for this to work.
First of all, let’s click «Actions» in your repository:
Then click on «Set up a workflow yourself» on the right side. In the new screen, you can write your configuration, but you can remove everything that’s there and paste this instead:
This configuration takes care of deploying your website automatically when you push changes to the master branch. All the way at the bottom you can see that we execute «npm run deploy». This is the script that we added to our package.json in step 5. When you run «npm run deploy», the following command will get executed:
Let’s analyze what this actually does. This command pushes a single folder, in this case «dist», to the gh-pages branch. That is the branch that we chose as our production branch in GitHub. This command will get executed every time we push to the master branch. Now every time you push your changes, GitHub Actions will automatically publish your «dist» folder. So that’s another thing you don’t have to think about anymore when deploying to GitHub Pages.
Conclusion
I hope this helps you to start deploying your own static websites to GitHub Pages and feel more empowered to update your own content, without needing the help of complicated deployment systems or a development team. Deployment of static websites really doesn’t need to be complicated or take any extra work. Through automation scripts, you can deploy changes by going through your normal workflow, just like you’ve been doing.
If you want to see an example of a website that’s currently running in production in the way that I’ve described in this tutorial, you can have a look at sandervolbeda/personal-website on GitHub.
H Итак, вы решили начать публиковаться на github в черновиках
Ответ на вопрос — «зачем мне это хотеть?» в обсуждении этой статьи.
Оговорюсь сразу — это вводный курс молодого бойца, не имеющего никакого понятия ни о гите ни о гитхабе. Это неправильный курс, единcтвенная задача которого — преодолеть порог вхождения и дать тот минимальный набор знаний, необходимых для того, что бы затем более опытные и правильные товарищи могли наставлять на путь истинный. Если же вы git-сихан, то не проходите мимо, дайте наставлений в комментах юным падаванам.
Что делаем? Если не зарегистрировались еще — регистрируемся: https://github.com
Авторизуемся, находим в правом верхнем углу такую картинку: .
Нажимаем на крестик, выбираем New repository.
Видим такую картинку:
Ничего страшного, заполняем. В repository name — краткое название репы на английском (может и на других языках можно, не проверял).
Description — описание репы, я сюда пишу собственно название статьи. Ставим галочку на Initialize this repository with a README, это говорит гитхабу о том, что в репу надо добавить README.md, который выполняет функции index.html для репы, то есть отображается для посетителя репозитория, если он явно не указал, какой файл хочет посмотреть. Почему md? Потому что markdown, подробности, как подсказывает spmbt, здесь:
help.github.com/articles/markdown-basics
help.github.com/articles/github-flavored-markdown
help.github.com/articles/writing-on-github
Ну что, жмем на большую зеленую кнопку create repository, получаем вот такой экран:
Внизу мы видим содержимое README.md, а сразу над ним — ссылку на этот файл. Жмем на ссылку и попадаем в экран редактирования файла:
Осталось только нажать на кнопочку с изображением карандаша (ручки) в верхнем правом углу панели инструментов. В этом меню можно вносить изменения, не забываем что мы в маркдауне а не в html. Ок. После внесения правок коммитим: . Все, вы умеете создавать и редактировать репозиторий на гитхабе!
После того, как разберетесь с маркдаун версткой, придет понимание того, что в одну репу можно класть несколько документов (новый файл создается нажатием крестика справа от названия репы:
), и вообще устраивать сложную иерархию. Это имеет смысл только для циклов статей или как то иначе связанных документов. Я предпочитаю для каждой статьи делать отдельную репу. Читатель, заинтересовавшийся статьей, может форкнуть репу, может отметить звездочкой и все такое. Если в репе много статей, то копируя репу, читатель получит все, что в ней есть, в том числе и то, что его не интересует. То же самое касается и подписчиков — подписавшись на репу из за одной статьи, подписчик будет получать уведомления по всем изменениям всех документов репозитория.
Ок, теперь у нас есть несколько статей (читай репозиториев), как бы нам их собрать в кучу (сделать личный хабик)? Как выяснилось (спасибо гитхаб-юзеру aol-nnov), гитхаб предоставляет простой способ хостить свои пожитки.
Что же. Англоязычновладеющие могут ознакомиться с оригиналом, я же опишу вкратце. Есть особый репозиторий, который автоматически хостится гитхабом как сайт. Для этого достаточно репозиторий назвать ВАШ_ЛОГИН.github.io, создать в нем index.html и закоммитить. После этого он (index.html) становится доступен по адресу ВАШ_ЛОГИН.github.io:
Но помним — тут уже верстка в html, не markdown. Можно ссылаться на другие документы этого же репозитория ссылками типа /путь к документу. Можно ссылаться на документы других своих репозиториев ссылками типа httрs://USER_NAME.github.io/REPO_NAME/путь к документу, но тут есть один нюанс — документ с другой репы публикуется только в том случае, если он есть в ветке gh-pages. Если такого документа в этой ветке нет или же нет самой ветки — выдаст 404. Что такое ветки — ниже будет ссылка на развитие кругозора, а пока же создадим такую ветку, не понимая глубины и широты происходящего, так же, как мы смотрим телевизор, не понимая механизма дифракции электронов на решетке или причин, по которым свободный электрон не поглощает фотон, в отличие от электрона на орбите. Все эти досадные помехи реальности не мешают нам наслаждаться очередной серией Симпсонов.
Ok, что делаем? Создадим ветку gh-pages в той репе, ссылки на документы из которой мы хотим разместить на своем публичном хабе.
То есть, к примеру, у нас есть репа test, и мы хотим что бы some_page.html из этой репы выводился у нас в user_name.github.io.
Идем в репу тест и находим вот эту кнопочку: .
Жмем на нее и вводим в поле ввода gh-pages:
Жмем enter, все! Ветка gh-pages создана! Теперь на все файлы репы можно ссылаться, формат ссылки я указывал выше.
Собственно все! Мы научились создавать документ, редактировать и публиковать его. За бортом остались форки, пулл-реквесты и мерджи, но для понимания этих моментов уже необходимо знать основы гита. А тут уже — обещанная ссылка: git book (без паники, на русском). Поймете основы гита — поймете основы гитхаба, ведь гитхаб — это гит с веб-обвесом и хорошо сдобренный community-building плюшками.