Repository files navigation

updated July 26, 2024

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.

Originally, GitHub Pages was intended for a project'sdocumentation. However, GitHub allows users to use itfor other purposes within certain boundaries. Forinstance, creating a site to promote your business isallowed as long as it complies with GitHub's terms ofservice. Aside from those limitations, you have theoption to use GitHub Pages when you want to displayinformation and share it with the rest of the world,just like a blogging site. You can even addadvertisements and donation buttons to enable financialsupport.

When creating digital content, it comes in handy to use aplaintext file. Markdown is an excellent format becauseit can easily be converted into HTML, which is theprimary format consumed by web browsers.

This also encourages writers to use GitHub as theirdevelopment site because it is more efficient,utilizinggit to record the file's history. WhileGoogle Docs has a similar version tracking feature,git offers more robust version control capabilities.

Additionally, if you want to distribute your content asa hard copy, you can simply right-click the page inGoogle Chrome and selectPrint to generate a PDFversion of your content. If you are creating contentfor another website, you can embed the page, and yourjob is done. You have the repository as the active sitefor development, potentially with collaboration fromothers, and the GitHub Pages generated page as theoutput.

If you need a Google Docs or Microsoft Word version ofyour content, you can copy the rendered Markdown filefrom GitHub and paste it into Google Docs or MicrosoftWord, and the format will generally remain correct withsome minor adjustments.

As you can see, using GitHub Pages is very practical.

1. Create a GitHub account if there is none.

2. Create a repository or use an existing one.For free accounts, GitHub does not allow youto host from a private repo.

3. Initialize the repo with aREADME.md, or create one if it doesn'texist. This file will serve as the default landing page on GitHub.Other options includeindex.html,index.htm orindex.md. Thesimplest method to create a web page is by using Markdown, but youalso have the option to write in HTML if you prefer. But if you arewriting a content, mostly you will use Markdown more than HTML.

   Note: While you can technically haveREADME.md,index.html,index.htm andindex.md in your repository, it's not standardpractice to include all four. GitHub Pages will prioritize them inthe following order:index.html,index.htm,index.md, and thenREADME.md. It's best to choose one primary file for your landingpage to avoid confusion.

4. Go toSettings of the repository and look for GitHub Pagesat the left side, it's justPages.

   • ClickNone to trigger the dropdown.
   • Selectmain from the dropdown, it will auto-select/root. Leave it as is.
   • Click "Save" to apply your changes.

5. Configure Your Site:

   • Go back to your repository.
   • Create a file named_config.yml.
   • Choose a theme provided by GitHub. For example:
     

6. Visit the site provided. The URL pattern for GitHub Pages sitestypically follows this format:https://<username>.github.io/<repository>/.You now have your web page.

By default, GitHub provides accounts and even Orgs a rootof your Web Page where all pages will be based from. Even ifyou don't initialize this repo, you can start enablingPages per repo.

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 isjdevfullstack.github.io. You can nowcustomize your root web page and it will be served by GitHub !However, you may skip initializing your root directory.

As was mentioned above, a default document willbe 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 for 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.

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

• gh-pages is a branch,to create this, go toBranch,type in the boxgh-pages then hit Enter.

So, what to use ? Here are some considerations:

• if you are creating tutorial like this page of mineyou are reading, simply use themain branch using theREADME.md file.

• the/docs folder is usual for those codebase withdocumentation. Other document generator also relies onthis folder.

• thegh-pages can be your choice when yourmainbranch is dedicated for your source codes and you wanta dedicated hosting directory

• themain branch can be the source when it's allabout building the site not related to coding, as ina pure Web Page

Finally, it's up to the preference of the user or the team.

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, just like in our example above.These themes will always 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.

For more information on customizing themes, visit theGitHub Pages Documentation.

GitHub Pages is known for hosting static sites, but what does "static" really mean?Does this imply that such sites cannot incorporate dynamic elements through JavaScript?

The term "static site" refers to the way content is served to the user. In a staticsite, all content is pre-generated into HTML files and delivered directly to thebrowser. This means there's no server-side processing or database interactionshappening in real-time when a user visits the site.

However, this doesn't mean static sites are devoid of interactivity or dynamism.Through client-side JavaScript, static sites can include dynamic behaviors such ascontent updates, animations, and interactions. JavaScript can also fetch data fromexternal APIs, bringing in dynamic content or functionality, albeit without directserver-side processing or database access on the hosting server.

The key limitation of static sites, particularly in the context of GitHub Pages, isthe absence of backend functionality. This means while you can fetch and displaydata from external sources, you cannot directly save data back to a server ordatabase through GitHub Pages. Any form of data storage or complex server-sidelogic would require external services or APIs.

In essence, static sites served through GitHub Pages offer a blend of performanceand security for delivering content, with the flexibility to incorporate dynamicelements via client-side JavaScript, making them suitable for a wide range ofapplications from personal blogs to documentation and portfolio websites.In short, it has its own advantages compared to a full-pledged website.

GitHub Pages can even host games if the code is purely written inJavaScript. To prove this, I deployeddemo games from Vanilla Web Projects using GitHub Pages:

https://jdevfullstack-projects.github.io/hangman-game/

https://jdevfullstack-projects.github.io/breakout-game/

Just an added section in here since we are dealing with Markdownand GitHub Pages. Do you think it's still worth writing ?

We might think blogging is already dead, with all thesevideo-based platforms like YouTube and now TikTok. There areeven dedicated sites for posting images alone.

If we compare how popular blogging was in the past versus today,let's also consider that it was the main platform back thenbefore the advent of different social media platforms.

Now, choices are diverse, so it might seem to be a dead platform.But as you can see, text-based sites are still very strong today.Digital written content is still popular, even printed books.Written content is mostly associated with high-quality, in-depthcontent. In short, it has its own place in the diverse world ofmedia consumption.

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://jdevfullstack.github.io

was built by GitHub Pages,Jekyll being the static site generator. It's that simple.

About custom domain in GitHub Pages:

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

• jdevfullstack Profile
• jdevfullstack Repos
• jdevfullstack Projects
• jdevfullstack Tutorials