eleventy-plugin-podcaster 0.9.0 → 0.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +12 -143
  2. package/docs/README.md +179 -0
  3. package/package.json +9 -1
package/README.md CHANGED
@@ -2,15 +2,6 @@
2
2
 
3
3
  `eleventy-plugin-podcaster` — or **Podcaster**, as we will call it from now on — lets you use Eleventy to create a podcast and its accompanying website. **Podcaster** creates the podcast feed that you submit to Apple Podcasts, Spotify or any other podcast directory. And it provides information about your podcast to your Eleventy templates. This means that you can include information about the podcast and its episodes on your podcast's website, creating pages for individual episodes, guests, topics, seasons or anything else at all.
4
4
 
5
- Plenty of services exist that will host your podcast online — [Spotify][], [Acast][], [Podbean][], [Buzzsprout][], [Blubrry][]. But none of these will allow you to own your podcast's presence on the web, and none of them will give you the freedom to create a site that presents your podcast in a way that reflects its premise, tone and style.
6
-
7
- But **Podcaster** will.
8
-
9
- [Spotify]: https://podcasters.spotify.com
10
- [Acast]: https://www.acast.com
11
- [Podbean]: https://www.podbean.com
12
- [Buzzsprout]: https://www.buzzsprout.com
13
- [Blubrry]: https://blubrry.com
14
5
 
15
6
  ## Installation
16
7
 
@@ -36,144 +27,22 @@ export default function (eleventyConfig) {
36
27
  }
37
28
  ```
38
29
 
39
- ## Podcast information
40
-
41
- Once you've installed **Podcaster** in your Eleventy project, the next step is to provide it with information about your podcast — the title, the owner, the category, the subcategory and so on. The easiest way to do this is to put all the information in your data directory in a `podcast.json` file.
42
-
43
- Here's an example.
44
-
45
- ```json
46
- {
47
- "title": "Flight Through Entirety: A Doctor Who Podcast",
48
- "description": "Flying through the entirety of Doctor Who. Originally with cake, but now with guests.",
49
- "siteUrl": "https://flightthroughentirety.com",
50
- "author": "Flight Through Entirety",
51
- "category": "TV & Film",
52
- "language": "en-AU",
53
- }
54
- ```
55
-
56
- [Read more about podcast information.](docs/podcast-information.md)
57
-
58
- ## Episode information
59
-
60
- For each podcast episode you create, you will also create a Eleventy template containing the information about it — the title, the release date, the episode number, the filename and so on. This template will have the tag `podcastEpisode`; its front matter will contain all of the information about the episode — title, release date, episode number and so on — and its content will contain the episode's show notes.
61
-
62
- Here's an example.
63
-
64
- ```yaml
65
- ---
66
- title: Entering a new Phase
67
- date: 2024-04-14
68
- tags:
69
- - podcastEpisode
70
- episode:
71
- filename: 500YD S1E1, Entering a New Phase.mp3
72
- seasonNumber: 1
73
- episodeNumber: 1
74
- size: 61231442 # bytes
75
- duration: 3778.482 # seconds
76
- ---
77
- A big week for beginnings this week, with a new Doctor, a new origin story for the Daleks, and a whole new approach to defeating the bad guys. Oh, and a new podcast to discuss them all on. So let's welcome Patrick Troughton to the studio floor, as we discuss _The Power of the Daleks_.
78
-
79
- ```
80
-
81
- [Read more about episode information.](docs/episode-information.md)
82
-
83
- ## The podcast feed
84
-
85
- To create your podcast feed, **Podcaster** needs both the information you've provided about your podcast and the information you've provided about your individual episodes.
86
-
87
- By default, your podcast feed will be located at `/feed/podcast.xml`, which means that the URL you submit to Apple Podcasts or Spotify (or wherever) will be `{{ podcast.siteUrl }}/feed/podcast.xml`
30
+ ## ➡ [Documentation and usage][docs]
88
31
 
89
- ## Using podcast information and episode information in templates
32
+ On GitHub, you can find [detailed documentation][docs] about how to provide **Podcaster** with the information it needs to create your podcast feed and about how to use that information when creating the templates for your Eleventy site.
90
33
 
91
- All the podcast and episode information you provide are made available to your templates through the data cascade, including `title` and `date`, as well as fields in the `podcast` and `episode` objects.
92
-
93
- Here's how you could use this information to describe a single podcast episode in a Liquid template.
94
-
95
- ```liquid
96
- <article>
97
- <h1>{{ title }}</h1>
98
- <p class="episode-number">Episode {{ episode.episodeNumber }}</p>
99
- <p class="release-date">{{ date | date: "%A %-e %B %Y" }}</p>
100
- <section class="content">
101
- {{ content }}
102
- </section>
103
- <audio controls src="{{ episode.url }}" preload="none">
104
- <p class="audio-details">
105
- Episode {{ episode.episodeNumber }}: {{ title }}
106
- | Recorded on {{ recordingDate | date: "%A %-e %B %Y" }}
107
- | {{ episode.size | readableSize }}
108
- | Duration {{ episode.duration | readableDuration }}
109
- | <a download href="{{ episode.url }}">Download</a>
110
- </p>
111
- </article>
112
- ```
34
+ [docs]: https://github.com/nathan-bottomley/eleventy-plugin-podcaster/tree/main/docs
113
35
 
114
- All podcast episode templates belong to the `collections.podcastEpisode` collection, which means you can list several episodes on a single page using [Eleventy's pagination feature][pagination]. In that case, each episode's information will be available in its [collection item data structure][item].
36
+ As well as creating your feed and providing information to your templates, **Podcaster** can optionally calculate the size and duration of your podcast MP3 files, as well as offering functionality for drafts and excerpts.
115
37
 
116
- [pagination]: https://www.11ty.dev/docs/pagination/
117
- [item]: https://www.11ty.dev/docs/collections/#collection-item-data-structure
38
+ ## Rationale
118
39
 
119
- > [!TIP]
120
- > `episode.size` gives you the podcast's size in bytes and `episode.duration`
121
- > gives you the duration in seconds. To include size and duration
122
- > in your templates in a human-readable format, use **Podcaster**’s filters
123
- > `readableSize` and `readableDuration`.
124
-
125
- ## Hosting
126
-
127
- You can host your podcast site — along with its feed — [the same way you would host any Eleventy site][hosting], using [a Jamstack provider][] linked to your source control repository or using [a classic web host][] which will allow you to upload the contents of your output directory.
128
-
129
- [hosting]: https://www.11ty.dev/docs/deployment/
130
- [a Jamstack provider]: https://www.11ty.dev/docs/deployment/#jamstack-providers
131
- [a classic web host]: https://www.11ty.dev/docs/deployment/#classic-web-hosts
132
-
133
- However, your podcast episode files should probably be hosted somewhere else, preferably on a Content Delivery Network (CDN), which will let your listeners download your episodes promptly and quickly.
134
-
135
- There are many options available, including [Digital Ocean Spaces][], [Linode Object Storage][], [Backblaze B2 Cloud Storage][] and [Cloudflare R2][].
136
-
137
- [Digital Ocean Spaces]: https://www.digitalocean.com/products/spaces
138
- [Linode Object Storage]: https://www.linode.com/products/object-storage/
139
- [Backblaze B2 Cloud Storage]: https://www.backblaze.com/cloud-storage
140
- [Cloudflare R2]: https://developers.cloudflare.com/r2/
141
-
142
- To find out how to set this up and how to make this work with **Podcaster**, [read more about hosting your podcast episode files][episode-file-hosting].
143
-
144
- [episode-file-hosting]: docs/hosting.md
145
-
146
- ## Optional features
147
-
148
- **Podcaster** also implements some optional features which are useful for creating podcast websites — **drafts** and **excerpts**.
149
-
150
- These are not fundamental features of a podcast website, which is why they are opt-in. You activate them by passing options to the `addPlugin` method in your configuration file.
151
-
152
- ```js
153
- eleventyConfig.addPlugin(podcaster, {
154
- handleDrafts: true,
155
- handleExcerpts: true
156
- })
157
- ```
158
-
159
- [Read more about optional features.](docs/optional-features.md)
160
-
161
- ## Podcaster in action
162
-
163
- I started podcasting and creating podcasting websites in 2014. At first I used Squarespace, then WordPress, and then Jekyll, before finally settling on Eleventy late in 2022.
164
-
165
- I now have seven podcast websites powered by Eleventy, and **Podcaster** was derived from the code I used to create them.
166
-
167
- Here's a list:
168
-
169
- - [Flight Through Entirety](https://flightthroughentirety.com), a _Doctor Who_ podcast flying through the entirety of the show's 60-something-year history.
170
- - [Untitled Star Trek Project](https://untitledstartrekproject.com), a _Star Trek_ commentary podcast, where two friends watch _Star Trek_ episodes from across the franchise, chosen (nearly) at random using [a page on the podcast website](https://untitledstartrekproject.com/randomiser).
171
- - [500 Year Diary](https://500yeardiary), another _Doctor Who_ podcast, where we look at the show's themes and ideas and some of the people involved in its creation.
172
- - [The Second Great and Bountiful Human Empire](https://thesecondgreatandbountifulhumanempire.com), a _Doctor Who_ flashcast, where we give our initial reactions to each episode of the post-2023 era of the show.
173
- - [Startling Barbara Bain](https://startlingbarbarabain), a commentary podcast on _Space: 1999_, a lavish and generally ridiculous British scifi show from the 1970s.
174
- - [Maximum Power](https://maximumpowerpodcast.com), a podcast about _Blakes 7_, a less lavish but more ridiculous British scifi show from the 1970s.
175
- - [Bondfinger](https://bondfinger.com), a James Bond commentary podcast that soon ran out of James Bond films and ended up spending its time drinking and watching terrible TV shows from the 1960s.
40
+ Plenty of services exist that will host your podcast online — [Spotify][], [Acast][], [Podbean][], [Buzzsprout][], [Blubrry][]. But none of these will allow you to own your podcast's presence on the web, and none of them will give you the freedom to create a site that presents your podcast in a way that reflects its premise, tone and style.
176
41
 
177
- ## Licence
42
+ But **Podcaster** will.
178
43
 
179
- This plugin is available as open source under the terms of the [ISC License](https://opensource.org/licenses/ISC).
44
+ [Spotify]: https://podcasters.spotify.com
45
+ [Acast]: https://www.acast.com
46
+ [Podbean]: https://www.podbean.com
47
+ [Buzzsprout]: https://www.buzzsprout.com
48
+ [Blubrry]: https://blubrry.com
package/docs/README.md ADDED
@@ -0,0 +1,179 @@
1
+ # eleventy-plugin-podcaster 🕚⚡️🎈🐀🎤📲
2
+
3
+ `eleventy-plugin-podcaster` — or **Podcaster**, as we will call it from now on — lets you use Eleventy to create a podcast and its accompanying website. **Podcaster** creates the podcast feed that you submit to Apple Podcasts, Spotify or any other podcast directory. And it provides information about your podcast to your Eleventy templates. This means that you can include information about the podcast and its episodes on your podcast's website, creating pages for individual episodes, guests, topics, seasons or anything else at all.
4
+
5
+ Plenty of services exist that will host your podcast online — [Spotify][], [Acast][], [Podbean][], [Buzzsprout][], [Blubrry][]. But none of these will allow you to own your podcast's presence on the web, and none of them will give you the freedom to create a site that presents your podcast in a way that reflects its premise, tone and style.
6
+
7
+ But **Podcaster** will.
8
+
9
+ [Spotify]: https://podcasters.spotify.com
10
+ [Acast]: https://www.acast.com
11
+ [Podbean]: https://www.podbean.com
12
+ [Buzzsprout]: https://www.buzzsprout.com
13
+ [Blubrry]: https://blubrry.com
14
+
15
+ ## Installation
16
+
17
+ To install the npm package, type this at the command line:
18
+
19
+ ```shell
20
+ npm install eleventy-plugin-podcaster
21
+ ```
22
+
23
+ And then include the plugin in your Eleventy configuration file.
24
+
25
+ ```js
26
+ // eleventy.config.js
27
+
28
+ import podcaster from 'eleventy-plugin-podcaster'
29
+
30
+ export default function (eleventyConfig) {
31
+ .
32
+ .
33
+ eleventyConfig.addPlugin(podcaster)
34
+ .
35
+ .
36
+ }
37
+ ```
38
+
39
+ ## Podcast information
40
+
41
+ Once you've installed **Podcaster** in your Eleventy project, the next step is to provide it with information about your podcast — the title, the owner, the category, the subcategory and so on. The easiest way to do this is to put all the information in your data directory in a `podcast.json` file.
42
+
43
+ Here's an example.
44
+
45
+ ```json
46
+ {
47
+ "title": "Flight Through Entirety: A Doctor Who Podcast",
48
+ "description": "Flying through the entirety of Doctor Who. Originally with cake, but now with guests.",
49
+ "siteUrl": "https://flightthroughentirety.com",
50
+ "author": "Flight Through Entirety",
51
+ "category": "TV & Film",
52
+ "language": "en-AU",
53
+ }
54
+ ```
55
+
56
+ [Read more about podcast information.](podcast-information.md)
57
+
58
+ ## Episode information
59
+
60
+ For each podcast episode you create, you will also create a Eleventy template containing the information about it — the title, the release date, the episode number, the filename and so on. This template will have the tag `podcastEpisode`; its front matter will contain all of the information about the episode — title, release date, episode number and so on — and its content will contain the episode's show notes.
61
+
62
+ Here's an example.
63
+
64
+ ```yaml
65
+ ---
66
+ title: Entering a new Phase
67
+ date: 2024-04-14
68
+ tags:
69
+ - podcastEpisode
70
+ episode:
71
+ filename: 500YD S1E1, Entering a New Phase.mp3
72
+ seasonNumber: 1
73
+ episodeNumber: 1
74
+ size: 61231442 # bytes
75
+ duration: 3778.482 # seconds
76
+ ---
77
+ A big week for beginnings this week, with a new Doctor, a new origin story for the Daleks, and a whole new approach to defeating the bad guys. Oh, and a new podcast to discuss them all on. So let's welcome Patrick Troughton to the studio floor, as we discuss _The Power of the Daleks_.
78
+
79
+ ```
80
+
81
+ [Read more about episode information.](episode-information.md)
82
+
83
+ ## The podcast feed
84
+
85
+ To create your podcast feed, **Podcaster** needs both the information you've provided about your podcast and the information you've provided about your individual episodes.
86
+
87
+ By default, your podcast feed will be located at `/feed/podcast.xml`, which means that the URL you submit to Apple Podcasts or Spotify (or wherever) will be `{{ podcast.siteUrl }}/feed/podcast.xml`
88
+
89
+ ## Using podcast information and episode information in templates
90
+
91
+ All the podcast and episode information you provide are made available to your templates through the data cascade, including `title` and `date`, as well as fields in the `podcast` and `episode` objects.
92
+
93
+ Here's how you could use this information to describe a single podcast episode in a Liquid template.
94
+
95
+ ```liquid
96
+ <article>
97
+ <h1>{{ title }}</h1>
98
+ <p class="episode-number">Episode {{ episode.episodeNumber }}</p>
99
+ <p class="release-date">{{ date | date: "%A %-e %B %Y" }}</p>
100
+ <section class="content">
101
+ {{ content }}
102
+ </section>
103
+ <audio controls src="{{ episode.url }}" preload="none">
104
+ <p class="audio-details">
105
+ Episode {{ episode.episodeNumber }}: {{ title }}
106
+ | Recorded on {{ recordingDate | date: "%A %-e %B %Y" }}
107
+ | {{ episode.size | readableSize }}
108
+ | Duration {{ episode.duration | readableDuration }}
109
+ | <a download href="{{ episode.url }}">Download</a>
110
+ </p>
111
+ </article>
112
+ ```
113
+
114
+ All podcast episode templates belong to the `collections.podcastEpisode` collection, which means you can list several episodes on a single page using [Eleventy's pagination feature][pagination]. In that case, each episode's information will be available in its [collection item data structure][item].
115
+
116
+ [pagination]: https://www.11ty.dev/docs/pagination/
117
+ [item]: https://www.11ty.dev/docs/collections/#collection-item-data-structure
118
+
119
+ > [!TIP]
120
+ > `episode.size` gives you the podcast's size in bytes and `episode.duration`
121
+ > gives you the duration in seconds. To include size and duration
122
+ > in your templates in a human-readable format, use **Podcaster**’s filters
123
+ > `readableSize` and `readableDuration`.
124
+
125
+ ## Hosting
126
+
127
+ You can host your podcast site — along with its feed — [the same way you would host any Eleventy site][hosting], using [a Jamstack provider][] linked to your source control repository or using [a classic web host][] which will allow you to upload the contents of your output directory.
128
+
129
+ [hosting]: https://www.11ty.dev/docs/deployment/
130
+ [a Jamstack provider]: https://www.11ty.dev/docs/deployment/#jamstack-providers
131
+ [a classic web host]: https://www.11ty.dev/docs/deployment/#classic-web-hosts
132
+
133
+ However, your podcast episode files should probably be hosted somewhere else, preferably on a Content Delivery Network (CDN), which will let your listeners download your episodes promptly and quickly.
134
+
135
+ There are many options available, including [Digital Ocean Spaces][], [Linode Object Storage][], [Backblaze B2 Cloud Storage][] and [Cloudflare R2][].
136
+
137
+ [Digital Ocean Spaces]: https://www.digitalocean.com/products/spaces
138
+ [Linode Object Storage]: https://www.linode.com/products/object-storage/
139
+ [Backblaze B2 Cloud Storage]: https://www.backblaze.com/cloud-storage
140
+ [Cloudflare R2]: https://developers.cloudflare.com/r2/
141
+
142
+ To find out how to set this up and how to make this work with **Podcaster**, [read more about hosting your podcast episode files][episode-file-hosting].
143
+
144
+ [episode-file-hosting]: hosting.md
145
+
146
+ ## Optional features
147
+
148
+ **Podcaster** also implements some optional features which are useful for creating podcast websites — **drafts** and **excerpts**.
149
+
150
+ These are not fundamental features of a podcast website, which is why they are opt-in. You activate them by passing options to the `addPlugin` method in your configuration file.
151
+
152
+ ```js
153
+ eleventyConfig.addPlugin(podcaster, {
154
+ handleDrafts: true,
155
+ handleExcerpts: true
156
+ })
157
+ ```
158
+
159
+ [Read more about optional features.](optional-features.md)
160
+
161
+ ## Podcaster in action
162
+
163
+ I started podcasting and creating podcasting websites in 2014. At first I used Squarespace, then WordPress, and then Jekyll, before finally settling on Eleventy late in 2022.
164
+
165
+ I now have seven podcast websites powered by Eleventy, and **Podcaster** was derived from the code I used to create them.
166
+
167
+ Here's a list:
168
+
169
+ - [Flight Through Entirety](https://flightthroughentirety.com), a _Doctor Who_ podcast flying through the entirety of the show's 60-something-year history.
170
+ - [Untitled Star Trek Project](https://untitledstartrekproject.com), a _Star Trek_ commentary podcast, where two friends watch _Star Trek_ episodes from across the franchise, chosen (nearly) at random using [a page on the podcast website](https://untitledstartrekproject.com/randomiser).
171
+ - [500 Year Diary](https://500yeardiary), another _Doctor Who_ podcast, where we look at the show's themes and ideas and some of the people involved in its creation.
172
+ - [The Second Great and Bountiful Human Empire](https://thesecondgreatandbountifulhumanempire.com), a _Doctor Who_ flashcast, where we give our initial reactions to each episode of the post-2023 era of the show.
173
+ - [Startling Barbara Bain](https://startlingbarbarabain), a commentary podcast on _Space: 1999_, a lavish and generally ridiculous British scifi show from the 1970s.
174
+ - [Maximum Power](https://maximumpowerpodcast.com), a podcast about _Blakes 7_, a less lavish but more ridiculous British scifi show from the 1970s.
175
+ - [Bondfinger](https://bondfinger.com), a James Bond commentary podcast that soon ran out of James Bond films and ended up spending its time drinking and watching terrible TV shows from the 1960s.
176
+
177
+ ## Licence
178
+
179
+ This plugin is available as open source under the terms of the [ISC License](https://opensource.org/licenses/ISC).
package/package.json CHANGED
@@ -1,11 +1,16 @@
1
1
  {
2
2
  "name": "eleventy-plugin-podcaster",
3
- "version": "0.9.0",
3
+ "version": "0.9.2",
4
4
  "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
5
5
  "main": "eleventy.config.js",
6
6
  "exports": {
7
7
  ".": "./eleventy.config.js"
8
8
  },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "https://github.com/nathan-bottomley/eleventy-plugin-podcaster.git"
12
+ },
13
+ "homepage": "https://github.com/nathan-bottomley/eleventy-plugin-podcaster/tree/main/docs",
9
14
  "type": "module",
10
15
  "scripts": {
11
16
  "test": "ava"
@@ -18,6 +23,9 @@
18
23
  "rss"
19
24
  ],
20
25
  "author": "Nathan Bottomley",
26
+ "engines": {
27
+ "node": ">=20"
28
+ },
21
29
  "license": "ISC",
22
30
  "dependencies": {
23
31
  "@11ty/eleventy": "^3.0.0",