gitHub pages

Getting Started

See Official tutorial for detail steps.

Basically, what you have to do is

1. Create .github.io repository
2. Choose theme on settings tab in GitHub

Customize pages

Before updating your repository, please see each repository here for your theme to check how to customize for your purpose.

The examples of customization are

1. Twitter share button: go to publish twitter button page.

Choose good theme

There are some pages to collect the themes of GitHub pages. These are the pages I checked.

• https://github.com/planetjekyll/awesome-jekyll-themes
• #jekyll-theme on GitHub
• My favorite jekyll themes on GitHub community forum

For me, these are the themes I thought they look good.

• https://github.com/Gaohaoyang/gaohaoyang.github.io
  • No instruction on setup
• https://github.com/pmarsceill/just-the-docs
  • Navigations can be configured on front matter in each page.
  • Search data can be generated by just-the-docs
• https://github.com/mmistakes/minimal-mistakes
  • Highly customizable
  • Navigations including sidebar have to be configured properly by yaml files.
  • Searching entire pages is enabled by default

The important things for me was sidebar and search features, and I did not have to update every pages for sidebar, so I chose minimal-mistakes theme.

Setup GitHub pages site locally

See this official page for more details for how to see GitHub pages locally.

Getting Started

In order to do it, you have to do followings:

1. Install bundler
2. Write Gemfile in the root directory of your GitHub repository.

    source 'https://rubygems.org'
   
    git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
   
    gem "jekyll", "~> 3.8"
    gem 'github-pages', group: :jekyll_plugins
   

3. Install the above packages by bundle install.
4. Run bundle exec jekyll serve and access http://localhost:4000 on your browser.

Troubleshootings

The warning message GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data. shows up when bundle exec jekyll serve.

Example

> bundle exec jekyll serve
Configuration file: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io/_config.yml
            Source: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io
       Destination: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
Invalid theme folder: _sass
      Remote Theme: Using theme mmistakes/minimal-mistakes
       Jekyll Feed: Generating feed for posts
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
                    done in 8.254 seconds.
 Auto-regeneration: enabled for '/Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Solution

See either of the ways in this document. In my case, I created the personal token in GitHub and set the value to the environment variable JEKYLL_GITHUB_TOKEN.

Details of the issue

This warning message is from jekyll-github-metadata, so you should just follow how to fix this. However, this is not a big issue as long as you do not run the jekyll with JEKYLL_ENV=production.

No repo name found when JEKYLL_ENV=production is set

Example

> env JEKYLL_ENV=production bundle exec jekyll serve

Configuration file: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io/_config.yml
            Source: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io
       Destination: /Users/at-ishikawa/src/github.com/at-ishikawa/at-ishikawa.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
Invalid theme folder: _sass
      Remote Theme: Using theme mmistakes/minimal-mistakes
       Jekyll Feed: Generating feed for posts
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
   GitHub Metadata: Error processing value 'url':
  Liquid Exception: No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository. in /_layouts/single.html
             ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository.

Solution

As error message said, set the repository: owner/repository in your _config.yml, for example. For other solution, see this official document.

Details of the issue

If you do not run jekyll with JEKYLL_ENV=production, the repository configuration is read from git remote -v result, but with JEKYLL_ENV_production, it’s not read. So, that’s why repository configuration has to be set. It’s from github-meatadata as of the version 2.13.

Minimal mistakes

Enable search on lunr

By following getting started on official page, search by lunr can be easily enabled. The default search engine is lunr, and it searches collections of jekyll. So in order to search pages except posts, those pages should be under a collection.

Enable comments

You can enable them by following the official document.

Jekyll

Jekyll is the site generator developed in ruby, and GitHub pages use it.

Collections

Collections are the grouped contents, and some common configurations among them can be applied easily, like default front matters. The directory name of collections must have the _ prefix like _docs, and if it has output: true configuration, then it’s exported to websites. In default front matters, the type of scope can have collection name, for example, in next configuration, docs collection has the default layout single.

collections:
  docs:
    output: true

defaults:
  # _docs
  - scope:
      path: ""
      type: docs
    values:
      layout: single

• 2024 2
• 2023 20
• 2022 11
• 2021 12
• 2020 21
• 2019 5