I enjoy teaching people about CSS and in particular CSS Layout, over the last year I’ve developed a course which, in entirety, is about two full days worth of material if taught in person.
As there is only one of me, and I can only take on a finite number of in-person engagements each year I decided to make that material available online in the form of a self guided CSS layout workshop. Having done that, my aim was to keep all of the material in sync. So, if you study online or with me in a workshop all of the material is right up to date with any changes to the Grid specification or other fast moving specifications I cover.
It made sense to maintain the online version as the source of truth. It is the most complete version of the material – I rarely do this as a full two day workshop. So when I run a workshop I need to do two things. I need to select the lessons that I want to teach in person, and I need to assemble myself a set of teaching notes to use on the day. This post will explain how I achieved this using Perch Runway, and Pandoc.
Perch Templates and my Lessons
Each lesson in my workshop is stored as a an item a Perch Runway Collection. Collections in Runway can be any type of data stored in a structured format, so I have one for lessons. When I created my Collection for the website content I created a Perch template, with fields for the different elements of a lesson. I’m using Perch Blocks to enable to building up of an individual lesson from various types of data, including videos and images.
This master template for the Collection becomes the schema for the content, and therefore the admin UI in the Control Panel.
I’ve also added to this template a field for notes used in the in-person version of the workshop only. As I don’t want these to display on the website I have added the suppress attribute set to true. I can now enter this content in the Perch Control Panel and store it alongside the lesson, but it won’t display when the lesson is displayed using this main template on the site.
On the CSS Workshop site I display these lessons in Categories and secure them according to which course people have purchased. You can see some of the lessons which are available as part of my free courses on Selectors and Length Units.
Choosing lessons for export
Setting up a page from which to select lessons to build up an in-person course was pretty simple due to the fact that I can pass in different templates to the perch_collection function when I call it from the page – I’m not restricted to the master template used for input. The first template I pass in simply displays the title of the course, along with a checkbox to select it, the value of that checkbox is the slug for that lesson.
I post that to another page which again uses the perch collection function to select the courses from the array of slugs passed to it. Then I use another template to re-present that content in a plain HTML format – this time also including those notes added in the Control Panel for in-person presentations only, and not displaying things like videos and figures that make no sense in my notes. I now have all of my notes in HTML format.
Turning my document into an EPUB
With a nice clean HTML document of my content, I can now create my teaching notes for the workshop. When I am presenting my Macbook Pro is hooked up to the projector, with the projector mirroring the screen so the students can code along with me as we work through the CodePen examples.
As I can’t have notes on the Macbook, I bring with me an iPad Mini and use that for notes. I realised when working out how best to display these notes that my iPad includes a perfect method of displaying text – iBooks – I just needed to get my notes into EPUB format and I could then take advantage of the inbuilt functionality of iBooks.
I was already aware that I could use Pandoc to convert HTML into an EPUB (which is essentially HTML in a specific structure), and so I take my exported HTML, and run it through Pandoc at the commandline:
> pandoc -o workshop.epub workshop.html --toc --toc-depth=1 This creates me an EPUB, and I can open that in iBooks. A few notes on using Pandoc.
Pandoc will treat an h1 heading in your document as a new chapter. In my case that meant each lesson would become a chapter.
In the command above I have asked Pandoc to create me a table of contents, with the doc flag, and use a table of contents depth of 1 – so the TOC only includes the level ones headings. If you had longer lessons it might be helpful to output headings down to level 2 to give you more of an index.
In this case I am happy just to use the default CSS styles, however you can pass a stylesheet into Pandoc using the --epub-stylesheet=book.css flag.
If you do want to edit your EPUB after exporting, then I would suggest opening it in Sigil, a free EPUB editor. You can then make any edits and save the document.
Other conversions
As I am using content already easily output as HTML, then converting from HTML makes sense for my scenario. However if all of your notes are offline you can also convert directly from Markdown with pandoc. Also, see my notes for turning an EPUB into a Mobi for use on the Kindle, if you want to use a Kindle to present from.
There are lots of ways this process could be improved. I could add a method to reorder content or to add additional content as I create the book. I could install Pandoc on my server and actually run the transformation there, downloading the EPUB. However this process took me about 30 minutes to get up and running, in a hotel room, when I first thought about it. If you do find yourself needing to create notes for some purpose, then hopefully this helps you too.