Pages

A markdown file without front-matter will not be converted.

Debugging pages online at Travis CI.

Jekyll plugins working in GitHub Pages are listed at https://pages.github.com/versions/.

site.categories and site.tags work only for posts not for pages.

http://vvv.tobiassjosten.net/jekyll/jekyll-tag-cloud/

posts in subdirectories

To list posts in a subdirectory/_posts/ directory, one has to use site.categories.subdirectoryName.

debugging on Travis CI

One does not have to install jekyll locally to compile the site before pushing it to github pages. Github pages will compile all files before serving them. One problem arises in this case. If Github pages fail to compile the site, it does not give the reason. In order to know the reason without installing jekyll locally, one can use an online service Travis CI to show the whole compile process. In order to do this, one needs to provide the following two files in his site’s root directory, .travis.yml and Gemfile as instructed on the Github help page. If one encounters building errors on Travis CI related to ruby verson, one can specify the ruby version in .travis.yml the following way:

language: ruby
rvm:
    - 2.1.0
script: "bundle exec jekyll build"

where, the ruby version is specified in the second and the third lines.

Sorted site.pages

According to issue 42 of plusjade/jekyll-bootstrap, Github sorts site.pages by the timestamps of the static html files. One can sort site.pages using the sort filter provided by liquid:

{% assign sorted = site.pages | sort:"path" %}
{% for each in sorted %}
  <li><a href="{{ each.path }}">{{ each.title }}</a></li>
{% endfor %}

According to stack overflow, custom attributes cannot be used for sortting. One has to use “path” (full path to the file) or “name” (name of the file) for sorting.

custom https domain

https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site

Modify default jekyll theme items

In _config.yml,

title: your site title
description: sub title
# get rid of view on github, download, etc. buttons
github:
  is_user_page: false
  is_project_page: false

The best way to find out these configuration options is to check the theme’s _layouts/default.html file.

Integrate Doxygen with GitHub pages

Set the docs folder in master branch as the source of GitHub Pages for a project using the web interface provided on https://github.com
Edit the following setting in Doxyfile to change the output directory of html documentations generated by Doxygen from html to docs:

HTML_OUTPUT = docs

Run doxygen to generate html files in docs/ and git add docs to put it under version control:

doxygen Doxyfile # generate html documents in docs/
git add docs # put docs under version control
git ci -m "added doxygen documents" Doxyfile docs # commit changes
git push # publish it in GitHub Pages

Acknowledgement

Activities mentions in this site have been supported by the following grants:

GitHub /cloud service hosting Git repositories/