Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/benbalter/jekyll-titles-from-headings
https://github.com/benbalter/jekyll-titles-from-headings
github-pages jekyll jekyll-plugin markdown
Last synced: 14 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/benbalter/jekyll-titles-from-headings
- Owner: benbalter
- License: mit
- Created: 2016-10-31T21:10:53.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2024-06-11T14:18:40.000Z (5 months ago)
- Last Synced: 2024-10-09T12:23:33.487Z (25 days ago)
- Topics: github-pages, jekyll, jekyll-plugin, markdown
- Language: Ruby
- Size: 128 KB
- Stars: 94
- Watchers: 7
- Forks: 24
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE.md
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: docs/SECURITY.md
Awesome Lists containing this project
- awesome-jekyll-plugins - **Title from Headings** - from-headings](https://rubygems.org/gems/titles-from-headings)) by Ben Balter -- pull page title from first markdown heading when none is specified (Settings & Configurations Tweaks)
README
# Jekyll Titles from Headings
*A Jekyll plugin to pull the page title from the first Markdown heading when none is specified.*
[](https://github.com/benbalter/jekyll-titles-from-headings/actions/workflows/ci.yml)
## What it does
If you have a Jekyll page that doesn't have a title specified in the YAML Front Matter, but the first non-whitespace line in the page is a Markdown H1 / H2 / H3, this plugin instructs Jekyll to use that first heading as the page's title.
## Why
Because lots of plugins and templates rely on `page.title`.
If you're using a plugin like [Jekyll Optional Front Matter](https://github.com/benbalter/jekyll-optional-front-matter), you'd have to add Front Matter, just to get the title, which you're already specifying in the document.
Additionally, this allows you to store the title semantically, in the document itself so that it's readable, both as Markdown and when rendered, as machine-readable for plugins like [Jekyll SEO Tag](https://github.com/benbalter/jekyll-seo-tag).
## Usage
1. Add the following to your site's Gemfile:
```ruby
gem 'jekyll-titles-from-headings'
```
2. Add the following to your site's config file:
```yml
plugins:
- jekyll-titles-from-headings
```
Note: If you are using a Jekyll version less than 3.5.0, use the `gems` key instead of `plugins`.
## Configuration
Configuration options are optional and placed in `_config.yml` under the `titles_from_headings` key. They default to:
```yml
titles_from_headings:
enabled: true
strip_title: false
collections: false
```
### Stripping titles
If your theme renders titles based on `page.title`, you can remove the title from the content by setting `strip_title` to prevent rendering it twice.
To limit this behavior to a certain layouts or paths, you can use [front matter defaults](https://jekyllrb.com/docs/configuration/#front-matter-defaults), e.g.
```yml
defaults:
- scope:
path: some-path
layout: some_layout
values:
strip_title: true
```
### Processing Collections
If you want to enable this plugin for collection items, set the `collections` option to `true`.
Since collection items (including posts) already have a title inferred from their filename, this option changes the behavior of this plugin to override the inferred title. The inferred title is only used as a fallback in case the document doesn't start with a heading.
### Disabling
Even if the plugin is enabled (e.g., via the `:jekyll_plugins` group in your Gemfile) you can disable it by setting the `enabled` key to `false`.