Ensure all pages have a unique title

[parkr]

All pages ought to have a unique title. For several pages, no title is specified. For all those pages, a headline is specified. Thus, falling back to a headline when a title does not exist fixes this problem.

[thelinuxfoundation]

Thank you for your pull request. Before we can look at your contribution, we need to ensure all contributors are covered by a Contributor License Agreement.

After the following items are addressed, please respond with a new comment here, and the automated system will re-verify.

• User @parkr isn't covered by a CLA. They will need to complete the form at https://identity.linuxfoundation.org/projects/cncf

Regards, CLA GitHub bot

[parkr]

Hello! I have been added to the “CNCF - GitHub” CLA. I should be good to go. Thank you!

[carl-mastrangelo]

@parkr forgive me for not doing my due diligence, but do all pages have a page.headline?

[parkr]

@carl-mastrangelo Not all pages do, no! But all pages which do not have titles do have headlines, so a fallback makes sense. Alternatively, we could add a title to all the pages which don’t have one!

[parkr]

@carl-mastrangelo I wrote a quick plugin to illustrate this. It simply iterates over all the pages which do not have a title and prints whether it has a headline.

cat _plugins/ensure_title.rb

# frozen_string_literal: true

class EnsureTitle < Jekyll::Generator
  def generate(site)
    site.pages.each do |page|
      next unless page.extname.eql?(".md")
      next if page.data['title']

      if page.data['headline']
        puts "No title, but has headline (#{page.path})"
      else
        puts "No title, no headline (#{page.path})"
      end
    end
  end
end

In the case that neither a headline nor a title exist in the front matter, we should see No title, no headline. In the case that a title does not a exist, but a headline does, we should see No title, but has headline.

When you run bundle exec jekyll build locally with this plugin, you see the following output:

No title, but has headline (docs/quickstart/android.md)
No title, but has headline (docs/tutorials/basic/android.md)
No title, but has headline (docs/guides/benchmarking.md)
No title, but has headline (docs/tutorials/basic/c.md)
No title, but has headline (docs/quickstart/cpp.md)
No title, but has headline (docs/quickstart/csharp.md)
No title, but has headline (docs/tutorials/basic/csharp.md)
No title, but has headline (docs/tutorials/basic/dart.md)
No title, but has headline (docs/quickstart/dart.md)
No title, but has headline (docs/reference/go/generated-code.md)
No title, but has headline (docs/reference/java/generated-code.md)
No title, but has headline (docs/reference/python/generated-code.md)
No title, but has headline (docs/quickstart/go.md)
No title, but has headline (docs/tutorials/basic/go.md)
No title, but has headline (docs/tutorials/async/helloasync-cpp.md)
No title, but has headline (docs/tutorials/basic/java.md)
No title, but has headline (docs/quickstart/java.md)
No title, but has headline (docs/quickstart/node.md)
No title, but has headline (docs/tutorials/basic/node.md)
No title, but has headline (docs/tutorials/auth/oauth2-objective-c.md)
No title, but has headline (docs/tutorials/basic/objective-c.md)
No title, but has headline (docs/quickstart/objective-c.md)
No title, but has headline (docs/tutorials/basic/php.md)
No title, but has headline (docs/quickstart/php.md)
No title, but has headline (docs/tutorials/basic/python.md)
No title, but has headline (docs/quickstart/python.md)
No title, but has headline (docs/quickstart/ruby.md)
No title, but has headline (docs/tutorials/basic/ruby.md)

This shows that for all pages without a title, a headline exists. This PR takes this fact and uses it to ensure the <title> field is always unique. For example, /docs/quickstart/ruby.html currently has the title grpc /. After this change, it has the title grpc / Ruby Quick Start.

[parkr]

Thank you very much! ✨