1. Introducing GitHub Pages
GitHub Pages is a fast and easy way to make a website that is hosted on GitHub. com. The code in your repo will be the code running the website. Even better is that it’s much easier to style your websites with Jekyll, a free, open-source site generator that takes Markdown files and creates websites with support for themes.
You can discover more about Jekyll at https://jekyllrb.com or even check out what it’s up to on its GitHub repo (https://github.com/jekyll/jekyll).
With GitHub Pages, you can create a website using Markdown or HTML/ JavaScript/CSS.
If you need help remembering what you can do with Markdown, visit the Markdown GitHub Guide at https://guides.github.com/features/mastering- markdown.
2. Turning a Project Repo into a Website
GitHub Pages is a great tool that is integrated into GitHub.com. GitHub Pages will look for a README.md file on your master branch and use it as the landing page for your website, meaning you don’t have to do much to get it up and running! Just follow a couple short steps:
- Open a repository on GitHub.com.
For this example, I use my HelloWorld repo that I create in Chapter 3.
- On the home page for the repo, click the Settings tab on the top right to open the Settings page.
The Options Settings page, shown in Figure 4-1, appears.
- From the Select source drop-down menu, change the source for GitHub Pages from none to master branch and then click Save.
The web page refreshes. If you scroll back to the GitHub Pages section, you see master branch under Source.
- Choose a theme for your website.
A new web page loads, as shown in Figure 4-2. Browse through the themes and choose one. For my example website for this book, I use the Time Machine theme.
- After you choose a theme for your website, click Select theme.
You return to the Settings page.
- Visit your project website.
Scroll back down to the GitHub Pages section on the Settings page for your repository, and you see a notification in green that your site has been published with a clickable URL.
If you don’t see that your site has been published, try refreshing the web page. Sometimes browsers will cache, and these changes won’t appear immediately.
7. Click the URL and view the website you just made.
3. Setting Up a Personal Website Repo
To create a new repo that houses your own personal website, you need to set up your repo:
- Create a new repository and name it github.io, where username is replaced with your actual GitHub username.
For example, the name of Sarah’s repository is sarah-wecan.github.io. If you’re unsure how to create a new repository, see Chapter 3.
- Make the repository public, initialize it with a README, choose a license, if you want, and then click Create Repository.
If you’re unsure whether you want a license, see Chapter 3, which describes the benefits of choosing a license.
The page refreshes to the home page of your new repository.
- Create a project with the Automated kanban template.
If you don’t know how to create a project, see Chapter 3 for guidance.
- At the top of your repo again, click the Settings tab and scroll down until you see the GitHub Pages section.
Notice that it says your site is already ready to be published at a certain URL (mine is https://sarah-wecan.github.io/). If you go to this URL, you should see a simple barebones web page with the contents of your README.md file. If you get a 404, just wait a moment and refresh the page.
It can take a few seconds for GitHub Pages to build your site.
- In the GitHub Pages section, click Choose a theme and then click Select theme.
If you’ve already chosen a theme and want to change it, this button is labeled Change theme. After you choose a theme, you’re taken to one of two pages, depending on which theme you chose. Either you’re taken back to the Settings page, from which you can navigate back to your code and you see a _config. yml file with your theme information. In this case, you can skip Step 6. Alternatively, you’re taken to the README.md file in editing mode, where the theme information has been added to the README. In this case, you should follow Step 6. In either case, the commit of the _config.yml file happens automatically, and that commit triggers GitHub Pages to rebuild your site with the theme applied.
- Commit your README.md file.
Your README.md file has now been modified to include information about your Jekyll template. Scroll to the bottom, add a title to the commit message, and choose Create a new branch for this commit and start a pull request. Then click Propose file change. The page refreshes with a new pull request ready to be created. You can merge your pull request. Then you can navigate back to your code, and you see the _config.yml file as described in Step 5.
- Create a pull request with a more inclusive title.
For instructions on creating a pull request, see Chapter 3.
Change the title of the pull request to describe everything you want to do for this iteration of your website and add a description. For example, I added the following list:
To create a basic website:
-
- [ ] Add a theme
- [ ] Add an index.md file with “Hello World” on it
- Link this pull request to the project and create the pull request.
To ensure your project board automatically tracks the progress of your website, choose the project created in Step 3 on the right side of the pull request from the Projects section. Then click Create pull request.
- Update the pull request when appropriate.
The description of a pull request is not static. When you first create a pull request, you may have a list of things you want to do before merging the code into the master branch. You may also end up making changes throughout. Make sure to always revisit the description and make sure it is accurate. For example, if you’re following these steps exactly, you have already chosen a theme, so you can check the first box.
10. Verify the project board automation.
Go back to the project board by clicking on the Projects tab at the top of your repo and notice that a new card is in the In progress column. This card has a checklist on it, just like the description of the pull request does, and you can see that one of two tasks has already been completed.
11. Switch to the pull request branch.
Go back to the Code tab of your repo and switch to the branch that is associated with your pull request. Mine is sarah-wecan-patch-1.
If you don’t know how to switch to a different branch on GitHub.com, see Chapter 3.
12. Create an index.md file
On the top right of your code file list, click Create new file. Name the file index.md and add a header that says “Hello World!”:
# Hello World!
Commit that file to the same branch you’ve been working on, with a title and commit message.
- Update and merge the pull request.
Go back to the pull request and check off the second check box. Because everything that you wanted to do for this pull request has been completed, the pull request can be merged. Click Merge pull request, Confirm merge, and then Delete branch.
14. Verify the project board automation.
The pull request shows in the conversation that it has been moved from the In progress column to the Done column. You can also go back to the project board. Notice that the card has moved to the Done column, and both checklist items have been completed.
15. Verify the website was published.
Go back to your URL (mine was https://sarah-wecan.github.io). You have a working website with the theme you chose.
If you don’t see the theme that you chose, try refreshing your web page. You now have a website that you can continue building and customizing as you do more and have more to share with the world.
4. Creating Issues for Your Website
After you have a GitHub.com website repository (see preceding section), you can think through the sections you want to have on your website. Creating issues for everything you want to add or change about your website can help you plan and remember all the little things you want to change.
Say that someone gives you a great suggestion. You don’t want to pull out your computer and make the change right then and there, but you can quickly jump on GitHub.com and create an issue to remind you to add it later. Creating an issue can also be useful if you are working on your website, and you’ve found something that is bothering you that you want to change. Instead of derailing what you’re already working on with a new task, you can just make a quick issue and get to it later.
To get started with this planning phase, go to the Issues tab on your repo and click New issue. Create an issue for all the things you want to add to your website.
In this book, I create four issues to use in my example:
» Change the title and tagline. The title and tagline of your website is currently something auto-generated. You probably want to change it to your name and some tagline that represents you. Create an issue, assigning yourself to it and linking it to your project board:
Issue Title: Change the title and tagline \
Issue Description: Make the title and tagline something unique to you.
» Add sections to the website. Without even having to leave an issue you created, you can click New issue and create another issue to add in sections to your website, assign yourself to the issue, and link it to your project board. In my example, I’ve chosen to add three sections:
Issue Title: Add a couple of sections to the website Issue Description: Add three sections to the website:
– [ ] About Me
– [ ] Contact Information
– [ ] Blog
» Write a blog post. Because one of the sections is to add a blog to the website, you may also want to actually publish your first blog post. Make a new issue to remind yourself, assign yourself to the issue, and link it to your project board:
Issue Title: Write a blog post about GitHub
Issue Description: With a blog section ready to go, add a
blog post that talks about your interactions with GitHub so far.
» Link your project repo. You can turn your project repo into a website, as described earlier in this chapter. Why not link that website from your personal website? Create an issue, assign yourself to the issue, and link it to your project board. Later, you can link to other projects that you contribute to or find interesting:
Issue Title: Link to the Project Repo
Issue Description: I’ve turned http://github.com/sarah- wecan/HelloWorld
into a website and I want to link that website from this one.
Four issues now appear under the Issues tab of my website repo, as shown in Figure 4-3. They also appear on my project board in the To do column (see Figure 4-4).
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.