Repository files navigation

From the definition of GitHub:

GitHub Pages is a static site hosting service designedto host your personal, organization, or project pagesdirectly from a GitHub repository.

GitHub Pages was added when GitHub was at its early stage.They sensed that a well-documented project is veryimportant, so they simplified the process.

Take note, GitHub Pages is not a Content ManagementSystem (CMS) like WordPress where a user can manage datathrough a database and all the backend scriptsfor a dynamic website but GitHub Pages caneven be more powerful than that.

For now, even for non-technical projects, GitHub Pagescan be used to generate static web pages. Just static?Well, from the definition of GitHub itself, you can't runserver-side scripting. But remember, Web 1.0was all about static web pages and we all knowthe advantages of static pages against dynamic ones.

Ideally, GitHub Pages was intended for a project'sdocumentation. However, GitHub allowed users to useit for other purposes within the boundaries given.For instance, creating a site to promote your businessis not allowed.But other than those limitations,you have the option to use GitHub Pageswhen you want to display informationand you want to share it to the rest of the world,just like a blogging site. You can evenadd an advertisement and donation button to enablefinancial support.

Remember, when you are creating a digital content,it's better to use a plaintext file. Markdown is thebest format, as it can simply be turned intoHTML. And as we know, when it's HTML format, that'sthe very consumption of web browsers, isn't it?

This also reinforces the writers to use GitHubas their development site because it is moreefficient as it usesgit to record thefile's history. Even if Google Docs has asimilar version tracking, stillgitcannot be replaced.

Now, here is the catch: when you want to distributeyour content as hard copy,in Google Chrome, you can simplyright click the page and clickPrintyou now have the PDF version of your content.Also, say, you are creating content for anotherwebsite, you can simply embed the page andyour job is done. You have the repo as theactive site for its development, maybe, otherswill collaborate too, and then the GitHub Pagesgenerated page as the output.If ever you need a Google Docsor Microsoft Wordversion of this, simply copy the renderedmarkdown file of GitHub and paste iton Google Docs or Microsoft Word, the formatwill still be correct.

As you can see, it's very practical.

In the same way you keep your pages and assets in onedirectory and subdirectories on the server, it isthe same thing in GitHub Pages through a GitHub repository.

For a user,<username>.github.io is the pattern by defaultso that GitHub Pages can build the site. Meaning, you shouldcreate a repository named after this pattern,so mine isxdvrx1.github.io.My site will be automatically created.However, you may skip initializing your root directory.

A default document will be displayed when a visitor requeststhe site's URL. This is theindex.htm file (orindex.htmlto make sure other platforms will read it correctly)unless you change this manually for the server to givea different default document.It is the same in GitHub Pages plus theREADME.mdorindex.md.So, when you create a repo, in GitHub Pages,you may have one default document from the three options:

• index.htm orindex.html
• README.md
• index.md

When you create a subdirectory,they are still the choices for thedefault document. The big advantage of using pure HTMLis the freedom to design your page.

There are three places where GitHub Pages will be buildingyour site from:main,gh-pages or/docs.

• Using themainbranch, there is no additional effort,just set the proper configuration inSettings.

• gh-pages is a branch,to create this, go toBranch,type in the box 'gh-pages'then hitEnter.

• /docs is a subfolder of the mainbranch,just clickCreate new file then type'docs/index.htm' or any of the otherchoices for the default document.GitHub does not allow empty repository,so you must initialize it with a file.In this example, that isindex.htm.

Furthermore, as I have observed when using just a regularaccount and when there is no need to change the domain name,it's just a matter of preference and technique where youwill be building your site among the three options.

But there are few considerations:

• First, themain branch can be the source when it's allabout building the site.

• Second, thegh-pages can be your choice when yourmainbranch is dedicated for your source codes.

• Third, the/docs folder is a good choice whenyou want to build your site from scratch whereyou don't copy the contents of themain branch,as in the case ofgh-pages branch.

Changing the default address is another story, whereyou really want to make sure that youhave an existing domain. If you know how to hosta site from your computer,this will be very easy for you to do. So,if you don't know the process yet, you find timestudying how to host a website from a different sourcebecause the idea is the same in GitHub Pages.I provided the link at the bottom.

The themes provided by GitHub Pages can be usedfor your pages. These themes willalways work in Markdown filesbut when you deal with pure HTML, make surethat you always delete the head section and just includethe body so that the theme you selected willbe the one to take care of your page/s.

Then tell Jekyll that through

---layout: default---

on top of the HTML file.

So, the steps are:

1. Create a GitHub account if there is none.

2. Create a repository or use an existing one.

3. Go toSettings and look for GitHub Pages.

4. Select where GitHub Pages should buildthe pages, either from:

   • master (default)
   • gh-pages
   • /docs

5. And select a theme also if you want.

6. You visit the site provided. You now have your web page.

GitHub Pages generates a static site butdon't you know that you can deploy games using this?The trick is actually the code: if that is purelyJavaScript, then it will work. To prove this, I deployeddemo games from Vanilla Web Projects using GitHub Pages:

https://xdvrx1.github.io/hangman-game/

https://xdvrx1.github.io/breakout-game/

As you can see here, because of the pure JavaScript,it enables the site not to be static. Remember,GitHub is referring to its being staticfor the server-side,so you can't directly run, say, a PHP script. Andsince JavaScript is browser-side scripting, itwill work as expected.

To my surprise, blogging is not dead.I simply had that conclusion realizingYouTube is a very successful platform.But written content is still not deadand it will continue to be relevant.

I just realized that blogging is notdead because not all the contentscan be done through video presentations.Others really need to be written.

Say, other tutorials are best donethrough video presentations just likebodybuilding demonstrations buttutorials in tech, particularly justlike the full documentation ofcomputer languages, are best done throughtext. Imagine if you will be doingall those through video presentations,first, that is not practical, secondit will take a lot of space and thatwill be problematic for poor connection.And third, it is best done throughwriting because the content is toocomplex there are several subheadings.

So, if you will be using GitHub Pagesto create written tutorials, you havethe full advantage of GitHub Pages versusall those blogging sites.

For further details, it is best to visit GitHub Pagesand other sites:

https://pages.github.com

https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages

https://help.github.com/en/articles/user-organization-and-project-pages

And it is important to know how GitHub Pagesdiffers from WordPress:

https://viktorsmari.github.io/2019/07/14/github-pages-vs-wordpress.html

For my very own example, this site

https://xdvrx1.github.io/C-Programming-Tutorial/

was built by GitHub Pages,Jekyll being the static site generator.When you clickView on GitHub, that is the repositorywhere all the assets and default documents reside.It's that simple.

And, for those who don't know yet how tohost a site using a computer as a server,

https://blog.mindorks.com/how-to-convert-your-laptop-desktop-into-a-server-and-host-internet-accessible-website-on-it-part-1-545940164ab9

About custom domain in GitHub Pages:

https://help.github.com/en/articles/using-a-custom-domain-with-github-pages

https://help.github.com/en/articles/custom-domain-redirects-for-github-pages-sites