These entries are written for the GitHub Pages environment but some apply to Jekyll in general.
There’s lots of cases where content (such as scripts) won’t be rendered properly on GitHub.com but will be rendered on GitHub Pages. Maybe you want to direct people from GitHub.com to GitHub pages, but don’t want that text to display on the GitHub Pages version.
Instead of having to maintain two different branches of content or just being content with ugly unrendered content on GitHub.com, do this:
<!--{% comment %}-->
# GitHub.com
This content will only be visible on GitHub.com.
<!--{% endcomment %}-->
{% comment %}
<!--{% endcomment %}
# GitHub Pages
This content will only be visible on rendered GitHub Pages.
{% comment %}-->
{% endcomment %}
Visitors to the markdown file on GitHub.com will see the following at the bottom of the document:
{% comment %}
{% endcomment %}
So this method isn’t perfect, but it’s much less distracting than before.
Sometimes you want page titles to be programmatically generated because you’re a lazy typer and setting front matter makes your document look ugly on GitHub.com. You can edit a theme to display the right title but then plugins like jekyll-seo-tag will use page.title for other things you can’t control, and that sucks.
GitHub Pages has the plugin jekyll-titles-from-headings, which sets the title based on the first Markdown heading it sees. That’s great except for when the theme already displays the page title so having a heading in addition to that is redundant and dumb.
Good thing the plugin has an option to strip out the heading it used as a title. Just add this to your _config.yml:
titles_from_headings:
strip_title: true
This option is how this repository can display in-markdown page titles on GitHub.com but only show them in the page header on GitHub Pages.
<ul>
{% for page in site.pages %}
{% if page.title %}
<li><a href="{{ page.url | split: ".html" | first | relative_url }}">{{ page.title }}</a></li>
{% endif %}
{% endfor %}
</ul>