Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nathan-bottomley/jekyll-podcast

A jekyll plugin for creating a podcast website
https://github.com/nathan-bottomley/jekyll-podcast

jekyll podcast

Last synced: 4 days ago
JSON representation

A jekyll plugin for creating a podcast website

Awesome Lists containing this project

README 

        
# Jekyll::Podcast



`jekyll-podcast` converts a Jekyll blog into a podcast webpage. It provides you with all the functionality you need to make your podcast fully accessible from your webpage, and it creates a podcast feed which you can submit to Apple Podcasts, Google Podcasts, Spotify or any other podcast directory.



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'jekyll-podcast'

```



And then execute:



```shell

bundle install

```



Or install it yourself as:



```shell

gem install jekyll-podcast

```



## Usage



### Providing information about your podcast



Most of the important information about your podcast — the title, the owner, the category, the subcategory and so on should appear in a `podcast` block in `_config.yml`.



```yaml

# _config.yml



podcast:

  title: "Flight Through Entirety: A Doctor Who Podcast"

  subtitle: &subtitle >-

    Flying through the entirety of Doctor Who. Originally with cake,but now with guests.

  # I've made the description and the summary

  # the same as the subtitle, but you can do

  # whatever you like here.

  description: *subtitle

  summary: *subtitle

  email: [email protected]

  language: en-AU

  author: Flight Through Entirety

  owner: Nathan Bottomley

  explicit: false

  category: TV & Film

  subcategory: TV Reviews

  complete: no

```



>Explanations of all of the fields here can be found on [Apple's page about podcast feed tags](https://help.apple.com/itc/podcasts_connect/#/itcb54353390). A list of podcast categories and subcategories [can be found here](https://podcasters.apple.com/support/1691-apple-podcasts-categories).



You will also need to provide your podcast artwork, which should be a JPEG file 3000 × 3000 pixels in size. `jekyll-podcast` will expect to find this file at `/assets/images/podcast-logo.jpeg`.



### Providing information about your podcast episodes



Each post in the `_posts` directory will correspond to an episode of your podcast. So, for example, the publication date of the post will be the publication date of the episode, and the content of the post will be the episode's description or shownotes, which will (normally) be displayed in your listeners' podcast player.



Other information about your podcast episodes should be provided in each post's front matter. Here's an example.



```yaml

tags: #optional

- Series 6

- The Eleventh Doctor

contributors: #also optional

- Nathan Bottomley

podcast:

  # the episode number

  episode: 217

  # the episode filename, including the extension

  file: >-

    FTE 217, Gaslight Girlboss Ginger (Day of the Moon).mp3

  # optional

  recording_date: 2021-08-01

```



### The episode files



By default, you will store your episodes in `/assets/episodes`, and they will be served directly from your website.



If you use an analytics service that requires a URL prefix to track your episodes' data, you will need to provide that prefix as part of the `podcast` block in `_config.yml`.



```yaml

# _config.yml



podcast:

  tracking_prefix: https://dts.podtrac.com/redirect.mp3

```



If you use a CDN or an S3-compatible storage solution to host your podcast episodes, you will need to provide the URL for that sevice. You must also store your episodes in a folder called `/_episodes`, so that Jekyll doesn't include the episode files in the website it builds.



```yaml

# _config.yml



podcast:

  remote_episode_host: https://flight-through-entirety.us-east-1.linodeobjects.com

```



> If you store your episodes on some other service, you will have to take care of uploading the episodes to that service yourself. I generally write a build script using `rsync` or `s3cmd sync` to do this.



### Creating your podcast feed



If you set up your `_config.yml` file and the front matter of your posts as specified above, `jekyll-podcast` will have enough information to create your podcast feed.



Your podcast feed will appear in your `_site` directory at `feed/podcast`.



### Your shownotes



The contents of each episode's post will appear on the website, as usual, but it will also be used as the description or shownotes for your episode and displayed in your listeners' podcast players.



It's easy to make a podcast player show a different description from the post displayed on your site. Just create an include called `post-feed-content.html` in the `_includes` folder and use it to define the content that you want to appear in a podcast player. Here's an example.



```html





  

    {{ post.star_trek.series }}, 

    {{ post.star_trek.episode }}.

    First broadcast on {{ post.star_trek.broadcast | date: "%A, %e %B %Y" }}

  




{{ post.content }}

```



### Podcast episode permalinks



Unlike a blog, a podcast website should have simple permalinks. Best practice tends to be just the episode number.



```url

https://flightthroughentirety.com/217

```



To make this possible, `jekyll-podcast` provides a `:podcast_episode` placeholder, which you can use in your default permalink definitions in `_config.yml`.



```yaml

# _config.yml



- scope:

    path: ""

    type: posts

  values:

    permalink: /:podcast_episode/

```



> You can combine this placeholder with other placeholders if you like. One possibility might be combining the episode number with the slug, like this:

>

> ```yaml

> # _config.yml

> 

> values:

>   permalink: /:podcast_episode-:slug/

> ```

>

>

> Remember to put the `/` at the end of the permalink pattern, so that you don't end up with the `.html` suffix at the end of your URLs.



### Podcast episode data



When `jekyll-podcast` builds your site, it analyses the podcast episodes in your `assets/episodes` folder (or your `_episodes` folder). As a result, the following information becomes available to your Liquid templates.



```liquid

{{ post.podcast.duration }} 

→ 0:57:22



{{ post.podcast.size_in_megabytes }}

→ 40.1 MB

```



You might want to consider adding the recording date to the podcast blog in the front matter of your posts, so that you can display it in your posts as well.



```yaml

podcast:

  recording_date: 2022-07-13

```



```liquid

{{ post.podcast.recording_date | date: "%A, %e %B %Y" }} 

→ Wednesday, 13 July 2022

```



### Including an `` tag



You should also create an include for your post so that your listeners can listen to the episodes on your website. The easiest way to do this is using an `` tag. `jekyll-podcast` provides a liquid filter called `episode_url`, which will add the correct URL to the filename you provide in your front matter.



Here's an example.



```html



```



### Podcast data



While `jekyll-podcast` is analysing your podcast files, it collects some interesting information about your podcast, and logs it to screen as part of the build process. This information includes the number of episodes, their total size in megabytes and their total duration (to the nearest millisecond).



```shell

236 episodes; 15786.9 MB; 9 d 16 h 6 min 25.577 s 

```



### Contributor pages



`jekyll-podcasts` has a feature which allows you to create bio pages for each of your contributors. These pages can include whatever information you like, including a chronological list of all of the episodes that a contributor has appeared in.



To get this to work, you need to create a Jekyll collection for your contributor pages. To do this, add a block like this to `_config.yml`.



```yaml

# _config.yml



collections:

  contributors:

    output: true

    permalink: /contributors/:slug/

```



Then create a layout for your contributor pages, and specify it as a default in `_config.yml`.



```yaml

# _config.yml



defaults:

  - scope:

      path: ""

      type: contributors

    values:

      layout: contributors-page

```



This layout should include the page content, and then iterate through the contributor's posts, which are all accessible to the layout and the page as `{{ page.posts }}`. Here's a simple example.



```html



page.title



{{ content }}



{% for post in page.posts %}

  

    
{{ post.title }}


    {{ post.content }}

  

{% endfor %}

```



Now you can create the contributor's pages. Each page can contain a picture, a bio and anything else you want. So long as you set the layout in the front matter to `contributors-page`, the pages will display all of the episodes that the contributor is involved in.



To indicate which contributors are involved in a particular episode, just add a list of contributors to the front matter of the corresponding post.



```yaml

contributors:

- Jonathan Archer

- Gabriel Lorca

- Christopher Pike

- James T Kirk

```



> Originally this feature was called _Guest pages_, and it's still possible to call this feature whatever you want. Just provide an replacement name in plural form to the `podcast` block in `_config.yml` as the `contributors_alias`, like this:

>

>```yaml

> # _config.yml

>

> podcast:

>  contributors_alias: guests

> ```

>

> If you do this, you should also change the name of the collection and the default type in `_config.yml` as shown above.



### Tag pages



There are plenty of other implementations of tag pages for Jekyll blogs, and so this one just aims to be as simple as possible.



To specify an episode's tags, just list them in the post's front matter.



```yaml

tags:

- The Tenth Doctor

- Specials

- Christmas

```



That's it really. By default, the permalink of a tag page will be the slugified version of the tag's text.



If you want to specify permalinks for a tag, you can do that by creating a file in the data directory called `tag_permalinks.yaml` or `tag_permalinks.json`. It should be a hash, with the tag as the key and the permalink as the value.



```yaml

# tag_permalinks.yaml



"Star Trek: The Next Generation": /tng/

"Star Trek: Deep Space Nine": /ds9/

"Star Trek: Voyager": /voy/

```



To create a list of tag links attached to a post, you can use `jekyll-podcast`'s `tag_link` filter, like this.



```html

{% for tag in post.tags %}

  {{ tag | tag_link }}

{% endfor %}

```



### The `pagetitle` tag



The `{% pagetitle %}` Liquid tag can be placed in the `` of your HTML layouts, and it will render a `` tag for your page. This tag will consist of the title of your page (as specified in the front matter), followed by an em-dash, followed by the title of your site (as specified in `_config.yml`). If your page has no title or if its title is the same as your site's title, the tag will just contain your site's title.



### `jekyll-podcast` in action



I've been using `jekyll-podcast` to create podcast websites since the middle of 2021, after hosting podcasts with WordPress for a number of years. It has allowed me to take more control of my podcast sites, and to spend my time writing HTML and Sass (and Ruby, I guess) instead of wrestling with WordPress plugins and PHP.



If you would like to see some podcasts powered by `jekyll-podcast`, here's a list of the podcasts I'm currently running.



- [Flight Through Entirety](https://flightthroughentirety.com), a _Doctor Who_ podcast flying through the entirety of the show's 60-year history.

- [Bondfinger](https://bondfinger.com), a James Bond commentary podcast that has run out of James Bond films and now spends its time drinking and watching terrible TV shows from the 1960s mostly.

- [Jodie into Terror](https://jodieintoterror.com), a _Doctor Who_ flashcast in which we give our (intermittently) enthusiastic hot takes on the most recent era of _Doctor Who_ mere days after each episode's first broadcast in the UK.

- [Untitled Star Trek Project](https://untitledstartrekproject.com), a _Star Trek_ commentary podcast in which two friends watch _Star Trek_ episodes from any series, chosen (nearly) at random by [a page on the podcast website](https://untitledstartrekproject.com/randomiser).



## License



The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).