Hyde Press

Octopod Documentation (Book Edition)

by Stefan Haslinger et al

A podcast publishing extension for the static site generator Jekyll.

Contents

Preface

Note: The book edition is still an early release and a work-in-progess.

This is the (official) documentation for Octopod reformatted in a single-page book edition.

See the source repo for how the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.

Onwards.

Acknowledgments

Thanks to Stefan Haslinger and all Octopod contributors for making it all possible.

Part 1 - Getting Started

Chapter 1.1 - Prerequisites

The Ruby programming language and its package manager Bundler.

Nice installation guides for the different operating systems can be found at the Rails Girls Website. You can stop right before installing Rails, because we do not depend on Ruby on Rails here.

You can check if you succeeded by entering

$ ruby -v
$ gem -v

at the command prompt. Both commands should return version greater or equal 2.0 .

Chapter 1.2 - Installation

First, install jekyll, create a new application and cd into it:

$ gem install jekyll
$ jekyll new name-of-my-podcast
$ cd name-of-my-podcast

Create a file Gemfile with the contents:

source 'http://rubygems.org'
gem 'jekyll-octopod'

This way, we tell Jekyll that we want to use Jekyll-Octopod. Now we install the Jekyll-Octopod and its dependencies and run the setup script via:

$ bundle install
$ octopod setup

The setup script copies all assets (for example the theme and templates) into your project. You should be prompted to overwrite a view files that are generated by Jekyll. If you answer the first question with capital Y, you won’t be asked again and all files are copied in batch.

Finally, generate the site and test drive it:

$ octopod build
$ octopod serve

Chapter 1.3 - Demo

Open a browser tab and navigate to http://localhost:4000. You should see the fully functional podcasting site like

Episode 0 is a demo episode. You can even listen to the nice tune Jazz Comedy from Bensound using the web player.

Chapter 1.4 - Usage

Next, update the configuration settings in the configuration file _config.yml in the application directory. (You are already in it.)

You can find a documentation of all the non-Octopod-specific settings on the Configuration page of the Jekyll Documentation.

Jekyll is highly customizable, if you are into coding (or even just want to get into it), read the Jekyll Documentation. It is very detailed and quite easy to grasp.

First of all, your new podcast episode needs audio data. Octopod assumes that your ready to use audio files stay within the episodes directory in your projects root.

$ cp ~/my_superduper_audio_files/ocp001.m4a episodes

In addition, jekyll-octopod assumes that the different audio files of each of your episodes are the same content in various formats – with the same duration and everything. If they are not, you may confuse your listeners – at least when you are using the chapters feature.

Next up, your episode needs some metadata. A title, some kind of a description, maybe chapters and so on. jekyll-octopod keeps all these metadata in one single text file (Protip: these dear little tots feel very lucky when they might live in a version control system!). jekyll-octopod kindly helps you to generate these files with the octopod episode command. You will get more information on the The command line tool later.

The following command

$ octopod episode --title "Why I <3 Octopod"

will generate you a template called YYYY-MM-DD-why-i-_3-octopod.md (YYYY-MM-DD represents the current date) in your _posts subdirectory. When you open it in your text editor you’ll see something like this:

---
title: Why I <3 Octopod
subtitle: A Subtle Subtitle
date: May 22nd, 2016
layout: post
author: Uncle Octopod
explicit: 'no'
audio:
  m4a: name.m4a
  mp3: name.mp3
  ogg: name.ogg
chapters:
- '00:00:00.000 Intro.'
- '00:00:30.000 Outro.'
---
##

{{ page | web_player:site }}


## Shownotes and Links

* Note

The part between the “---” and the “---” is the YAML front matter. This is where all the metadata is stored. Below the YAML frontmatter is the area (body) where you can write down your post’s content (like the show notes and stuff). This strange looking {{ page | web_player:site }} thingy is the Liquid filter, which represents the iframe where the web player will be included later.

When all this work is done you are ready to take a first look. The following command generates your site and starts a local webserver for a preview. You can check your new podcasting website by opening http://localhost:4000.

$ octopod --url "http://localhost:4000" --server

If everything is alright you can finally generate your “real” Site:

$ octopod

And deploy it to your server:

$ octopod deploy

Warning: The Rsync settings in your _config.yml are mandatory for this last step. But it is no problem to upload the generated website from the _site subdirectory via FTP or something.

Chapter 1.5 - The command line tool

The octopod-jekyll command line commands are:

$ octopod b[uild]
# builds from current path . to ./_site

$ octopod build <path/to/target>                   
# compiles and builds the site from the current path . to path/to/target

$ octopod build <path/to/source> <path/to/target>  
# compiles from source_path to  path/to/target

$ octopod import <importer name> <options>
# imports posts using named import script

$ octopod setup
# Sets up Jekyll site to become podcast-aware, copies assets and default config.
# Asks for confirmation on file overwrite.

$ octopod episode
# adds a post for a new episode

$ octopod deploy
# deploys your site via rsync

$ octopod <command> --help
# for more information on a specific command.

$ octopod s[erver]
# Starts the server

Configuration is read from <source>/_config.yml but can be overridden. Available options are documented in _config.yml. In case, you deleted some of the options, a full reference can be found in _config.yml.sample.

All derived Jekyll command line tasks can be found in Jekyll’s Usage Documentation, from which the octopod command inherits most of its functionality.

Chapter 1.6 - Liquid filters

Because Jekyll uses Liquid for template processing, jekyll-octopod does so, too. Along with the standard liquid tags and filters, Jekyll adds a few of its own and jekyll-octopod adds a few more which are documented on this page.

Filters

CDATA escape

Escapes some text for CDATA


{{ page.content | cdata_escape }}

JSON escape

Escapes HTML entities in JSON strings.


{{ page.some_string | j }}

Expand URLs

Replaces relative urls with full urls


{{ "about.html" | expand_urls }}             => "/about.html"
{{ "about.html" | expand_urls:site.url }}    => "http://example.com/about.html"

Remove Script and Audio tags

Removes unwanted tags from shownotes


{{ page.content | remove_script_and_audio }}

Http Only

changes url from requesting https to http


{{ url | http_only }} => "http://..."

Time to RSS schema

Formats a Time to be RSS compatible.


{{ site.time | time_to_rssschema }} => "Wed, 15 Jun 2005 19:00:00 GMT"

Otherwise

Returns the first argument if it’s not nil or empty – otherwise it returns the second one.


{{ post.author | otherwise:site.author }}

Select audio file from hash

Returns the value of a given hash. If no key is given as a second parameter, it first tries “mp3”, then “m4a” and then it will return a more or less random value.


{{ post.audio | audio:"m4a" }} => "my-episode.m4a"

MIME type

Returns the MIME-Type of a given file format.


{{ "opus" | mime_type }} => "ogg; codecs=opus"

File size

Returns the size of a given file in bytes. If there is just a filename without a path, this method assumes that the file is an episode audio file which lives in /episodes.


{{ "example.m4a" | file_size }} => 4242

Slug

Returns a slug based on the id of a given page.


{{ page | slug }} => '2012_10_02_octopod'

Split chapter

Splits a chapter, like it is written to the post YAML front matter, into the components ‘start’ – which refers to a single point in time relative to the beginning of the media file – and ‘title’ – which defines the text to be the title of the chapter.


{{ '00:00:00.000 Welcome to Octopod!' | split_chapter }} =>
                    { 'start' => '00:00:00.000', 'title' => 'Welcome to Octopod!' }
{{ '00:00:00.000 Welcome to Octopod!' | split_chapter:'title' }}  => 'Welcome to Octopod!'
{{ '00:00:00.000 Welcome to Octopod!' | split_chapter:'start' }}  => '00:00:00.000'

Audio tag

Returns an <audio> tag for a given page with <source> tags in it for every audio file in the page’s YAML front matter.


{{ page | audio_tag:site }}

Web player moderator

Returns the web player iframe for the episode of a given page.


{{ page | web_player_moderator:site }}

Web player

Returns the web player for the episode of a given page, to be used in the file created for the iframe mentioned above.


{{ page | web_player:site }}

Web player script tag

Returns the script tag initializing the web player for the episode of a given page, to be used in the file created for the iframe mentioned above.


{{ page | web_player_script_tag:site }}

String of duration

Gets a number of seconds and returns a human readable duration string of it.


{{ 1252251 | string_of_duration }} => "00:03:13"

String of size

Gets a number of bytes and returns a human readable string of it.


{{ 1252251 | string_of_size }} => "1.19M"

Host from URL

Returns the host of a given url


{{ 'https://github.com/pattex/octopod' | host_from_url }} => "github.com"

Disqus configuration

Generates the config for disqus integration. If a page object is given, it generates the config variables only for this page. Otherwise, it only generates the global config variables.


{{ site | disqus_config }}
{{ site | disqus_config:page }}

SHA1

Returns the hex-encoded hash value of a given string. The optional second argument defines the length of the returned string.


{{ "Octopod" | sha1 }}    => "8b20a59c"
{{ "Octopod" | sha1:23 }} => "8b20a59c8e2dcb5e1f845ba"

Returns a ready-to-use navigation list of all pages that have navigation set in their YAML front matter. The list is sorted by the value of navigation.


{{ site | navigation_list:page }}

Episode feeds

Returns an array of all episode feeds named by the convention episodes.<episode_file_format>.rss within the root directory. Also it contains all additional feeds specified by additional_feeds in the _config.yml. If an episode_file_format or key of additional_feeds equals the optional parameter, it will be skipped.


{{ site | episode_feeds }}
{{ site | episode_feeds:mp3 }}

Episode feeds HTML

Returns HTML links to all episode feeds named by the convention episodes.<episode_file_format>.rss within the root directory. Also it returns all additional feeds specified by additional_feeds in the _config.yml. If an episode_file_format or key of additional_feeds equals the optional parameter, it will be skipped.


{{ site | episode_feeds_html:'m4a' }} =>
<link rel="alternate" type="application/rss+xml" title="mp3 Episode RSS-Feed"
      href="/episodes.mp3.rss" />
<link rel="alternate" type="application/rss+xml" title="Torrent Feed m4a"
      href="http://bitlove.org/octopod/octopod_m4a/feed" />
<link rel="alternate" type="application/rss+xml" title="Torrent Feed mp3"
      href="http://bitlove.org/octopod/octopod_mp3/feed" />

Episode feeds RSS

Returns RSS-XML links to all episode feeds named by the convention episodes.<episode_file_format>.rss within the root directory. Also it returns all additional feeds specified by additional_feeds in the _config.yml. If an episode_file_format or key of additional_feeds equals the optional parameter, it will be skipped.


{{ site | episode_feeds_rss:'m4a' }} =>
<atom:link rel="alternate" href="/episodes.mp3.rss"
           type="application/rss+xml" title="mp3 Episode RSS-Feed"/>
<atom:link rel="alternate" href="http://bitlove.org/octopod/octopod_m4a/feed"
           type="application/rss+xml" title="Torrent Feed m4a"/>
<atom:link rel="alternate" href="http://bitlove.org/octopod/octopod_mp3/feed"
           type="application/rss+xml" title="Torrent Feed mp3"/>

Chapter 1.7 - The post structure

The post template can be found in /includes/post.html. It renders the posts from the /_post directory. Each post has to have a certain structure which consists of the YAML front matter and of the body part.

The YAML front matter

jekyll-octopod’s YAML front matter is an extension of Jekyll’s YAML front matter.

The attributes that can be set here are best described with the following example; they are quite self-explanatory:

title: Episode 0
subtitle: Getting Started Is Never Easy
summary: Otherwise the summary is the first paragraph of the show notes
episode-cover: "/img/episode-cover0.jpg'
datum: March 22nd 2016
layout: post
author: Arne and Stefan
explicit: 'no'
duration: "0:03:13"
audio:
  mp3: episode0.mp3
  ogg: episode0.ogg
  m4a: episode0.m4a
chapters:
  - '00:00:00.000 Intro.'
  - '00:00:30.000 ... Shoubidoubidoo ...'
  - '00:02:45.000 Outro.'
tags:
  - "a tag"
  - "another tag"
posts-dir: "/path/to/post/dir" # default: '_posts'

The body

The body part can contain arbitrary markdown content.

At minimum a short text, the web player (embedded in an iframe) and some links are recommended. For example:

Getting started is hard.

{{ page | web_player_moderator:site }}

## Show Notes und Links

  * Link lists are easily created: [Aua-uff-Code! Podcast](https://aua-uff-co.de)
  * another link to [Jekyll](https://jekyllrb.com/)

Audio and script tags get filtered out of the body for feed creation, so that they do not disturb in podcatchers rendering the shown notes.

Part 2 - Appendix

Chapter 2.1 - Contributions

Bug reports and even more push requests are highly welcome!

At the moment jekyll-octopod is completely made to fit my personal needs and preferences. But it’s a high priority goal for jekyll-octopod to become more generic. This and of course bug fixes would make the sweet little octopod mascot smile the most.

But feel free to fork and push request and code and everything. If you want to contribute:

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Chapter 2.2 - Credits

This Gem is sitting on the shoulder of giants, most of the code was not written by me and/or depends on other code.

Especially to be mentioned:

The beautiful Octopod Logo was designed and created by Thekla “TeMeL” Löhr. Please support her with a little flattr. Flattr this

Chapter 2.3 - License

jekyll-octopod is licensed under the MIT-License.

The following assets from separate projects are packaged in this repo:

Congrats – you have read all there is to read!