Page titles are taken from the first heading if no title exists

[brownsarahm]

The layout for the page reference says the title should be "References" which is then what the included on all pages main title should use, but somehow it's getting the first heading content in the page's content (not including the "key points" heading which comes from an include) on both instructor training and dc-ecology-python

We have a PR to IT attempting to override this, but it seems like unintended behavior all around?

[maxim-belkin]

I am pretty sure this is due to all of these lessons having "outdated" reference page template: they don't specify the title. Instead of setting the title to "Keypoints and References", I'd suggest to copy the contents of "reference.md" file from this repository verbatim to avoid future merge conflicts when syncing up with the styles repo.

[brownsarahm]

_layouts/reference.md in this repo and IT appears to match?

[zkamvar]

They do match. I'm not sure what is happening, but I would not be surprised if Jekyll is helpfully filling the page.title element. There should not be any problem with editing the title of reference.md (which does work) since that's not part of the template (it's a generated file).

[zkamvar]

This is a problem on pretty much any lesson where reference.md does not have a title: yaml item. Programming with R and Git Novice both show this issue.

[zkamvar]

The solution for new lessons would be to add the title header in https://github.com/carpentries/styles/blob/gh-pages/bin/boilerplate/reference.md, but for the other lessons, it might just be to create pull requests that adds the title to the reference pages.

[zkamvar]

After running a few tests, it appears that this will affect all of the pages in a lesson that do not have titles. If the first element of a page is a header element, then Jekyll will interpret that as the page.title

Examples

A page without a title element:

---
layout: page
---

Title: {{ page.title }}

## Heading 1 

<p>Title: </p>

<h2>Heading 1</h2>

A page with the title element:

---
layout: page
---

## Heading 1

Title: {{ page.title }}

<h2>Heading 1</h2>

<p>Title: Heading 1</p>

[zkamvar]

As I suspected, this is coming from a feature on GitHub pages. They have the jekyll-titles-from-headings plugin enabled (as shown in https://pages.github.com/versions/).

In order to turn this behaviour off, we need to set the following in the _config.yml:

titles_from_headings:
  enabled: false

[maxim-belkin]

_layouts/reference.md in this repo and IT appears to match?

The _layouts directory contains HTML files. I was talking about reference.md in bin/boilerplate.

There should not be any problem with editing the title of reference.md (which does work) since that's not part of the template (it's a generated file).

It's copied from bin/boilerplate when the lesson is created. Perhaps, we should move the common title from the reference.html file in the _layouts folder to .md file in bin/boilerplate.

[maxim-belkin]

I do agree, however, that it should be safe to redefine the title in the file.