How to customize a GitHub Pages theme layout

[ebeshero]

Customizing a GitHub Pages Layout is a little challenging, but you can do it with just a beginner's experience with code if you're determined and observant. The challenge is learning how to read and find just the code you need and figuring out how to adapt it from examples. I can get you started with my own experience doing this.

• Begin with GitHub Pages' own brief explanation of how to customize a theme layout: https://docs.github.com/en/github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-using-jekyll#customizing-your-themes-html-layout

• Find the GitHub repo for the theme you're using here: https://pages.github.com/themes/ You can try forking or cloning that repo if you like, or just find and download the _layouts folder.

• Bring your theme's _layout folder into your GitHub repo docs/ directory that is hosting your website. (You can do that by pushing the folder up into your own repo, or adding it by upload, but be sure you put it in the correct place, inside your docs/ directory.)

• Open the _layouts folder and look at the default.html file. Can you match up the pieces of code that deliver the structure of the webpages on your GitHub Pages site? Can you see what creates the banner, for example, and the link to your GitHub code repo?

• Think about how you want to edit this. Do you want to customize the banner and add buttons? Plan out what you want, and then see if you can modify the code.

  • For example, here is what the Cayman Theme looks like on GitHub Pages without modifying it: https://pages-themes.github.io/cayman/
  • Here is the code for the Cayman Theme pages in _layouts/default.html: https://github.com/pages-themes/cayman/blob/master/_layouts/default.html
  • Can you see the part that controls the buttons on the menu?

@am0eba-byte @arrowarchive and anyone else looking to modify GitHub Pages themes

[ebeshero]

Here is how I modified the Cayman Theme to add my own buttons on this site: https://digitalmitford.github.io/DigMitCS/

I followed the steps above to bring the Cayman Theme's _layouts/ folder into my repo.

Then I took a look at this code in _layouts/default.html:

    <header class="page-header" role="banner">
      <h1 class="project-name">{{ page.title | default: site.title | default: site.github.repository_name }}</h1>
      <h2 class="project-tagline">{{ page.description | default: site.description | default: site.github.project_tagline }}</h2>
      {% if site.github.is_project_page %}
        <a href="{{ site.github.repository_url }}" class="btn">View on GitHub</a>
      {% endif %}
      {% if site.show_downloads %}
        <a href="{{ site.github.zip_url }}" class="btn">Download .zip</a>
        <a href="{{ site.github.tar_url }}" class="btn">Download .tar.gz</a>
      {% endif %}
    </header>

I could see that this code was creating the buttons that I can see on the Cayman theme page:

So, I modified that code to add my own button names and simplified it so the buttons would always appear. (In the code above, two of the buttons only appear if there's a set of files to download. )

    <header class="page-header page-header-subpages">
      <!--<h1 class="project-name">{{ site.title | default: site.github.repository_name }}</h1>-->
      <h1 class="project-name"><a href="{{ site.baseurl }}/index.html" class="link-no-style">Digital Mitford Coding School</a></h1>
     <!-- <h2 class="project-tagline">May 2019 agenda and workshop resources</h2>-->
      {% if site.github.is_project_page %}
      <a href="{{ site.baseurl }}/nav.html" class="btn">Arrival info</a>
      <a href="{{ site.baseurl }}/index.html" class="btn">Daily schedule</a>
      <a href="{{ site.baseurl }}/instructors.html" class="btn">Instructors</a>
      <a href="{{ site.baseurl }}/restaurants.html" class="btn">Restaurant guide</a>
      {% endif %}
      {% if site.show_downloads %}
        <a href="{{ site.github.zip_url }}" class="btn">Download .zip</a>
        <a href="{{ site.github.tar_url }}" class="btn">Download .tar.gz</a>
      {% endif %}
    </header>

My new heading bar now has the navigation buttons customized for my site!

Squishing my menu bar into a smaller space was a different project. That involved adding and pointing to some styling code in a CSS file here: https://github.com/DigitalMitford/DigMitCS/blob/master/docs/local.css

[arrowarchive]

@ebeshero, I got the profile picture to work, but now I have an interesting problem. The picture shows up when I'm on my FAQ, Archive page, Main Page, and the "More About Me" page, but when I open up an image in the archive, the icon disappears and only the alt text is visible. You can see this for yourself if you view an image in my archive, but I don't know if it's a layout issue or an issue with the code.

[arrowarchive]

@ebeshero As of today, I have 140 commits in my repo. That will increase after adding my reflection, and I have a feeling that number will keep increasing.

Maybe at a later time, I'm considering adding some code to the website that will prevent most people from downloading images. A number of reposted images are downloaded through right-clicks then saving the image, so that would be a form of securing the website. I'd have to research it more, but if that's possible, it would be super helpful.