<commit_before>---
layout: post
title: "Publishing with GitHub pages"
date: 2013-09-25 14:56
comments: true
categories: blog
share: true
tags:
- open-access  
- open-source  
- publishing  
- GitHub  
- Hybrid Pedagogy  
- FlipCamp  
- Engaging Students
---

This week, I helped the folks at [Hybrid Pedagogy](http://www.hybridpedagogy.com) publish [an ebook on open online learning](http://learnerexperiences.hybridpedagogy.com). Like [*Engaging Students: Essays in Music Pedagogy*](http://flipcamp.org/engagingstudents), and all of my course websites, we published it using GitHub's free web hosting option. I've written about [why one might want to use GitHub](http://hybridpedagogy.com/Journal/files/GitHub_for_Academics.html) for a project like this before, so this post will not explain why. Instead, I'd like to explain *how* for all those interested in this process, particularly those who want to pursue open-access or open-source academic publishing.

## Setting up a blank ebook ##

Since the ebooks I've built have essentially been websites, any host, platform, or design is fine. However, GitHub allows any public project—including websites—to be "forked," or copied for remixing and republishing. The easiest way to publish an ebook, then, is to fork an existing ebook and replace the content. I have a template anyone can copy ([source](http://github.com/kshaffer/GHbook) | [site](http://kris.shaffermusic.com/GHbook)), or you can fork *Engaging Students* ([source](http://github.com/flipcamp/engagingstudents) | [site](http://flipcamp.org/engagingstudents)) or the HP project, *Learner Experiences* ([source](http://github.com/hybrid-pedagogy/LearnerExperiencesInMOOCs) | [site](http://learnerexperiences.hybridpedagogy.com/)).

## Google Drive ##

The content for both the FlipCamp and HP projects began with Google Docs. These are easy to produce, and they involve as much new technology as I am comfortable asking most people to wrestle with when submitting something to a publishing project. HP asks authors to compose articles in Google Docs and submit by sharing them with the editors; we used the same process for *Engaging Students*. *Learner Experiences* involved student essays which were uploaded to GDocs for the editing and publishing process.

## Exporting Google Docs for GitHub ##

Of course, GitHub will not simply publish Google Docs. GitHub can publish HTML pages, or it can use the open-source application Jekyll to convert any MarkDown or Textile files to HTML for web publication. And if you want to publish the ebook in ePub, Kindle, or PDF format, MarkDown is helpful there as well. So we want each article in a MarkDown file.

Google Docs does not support MarkDown. However, Google Docs can be exported in a number of file formats, which can in turn be converted to something GitHub can deal with. Each brings its own problematic aspect to that process, but I've found one almost ideal solution.

First, we exported all the Google Docs as HTML files.

Next, we converted those files to MarkDown, using the following code for each file (you may need to download and install [Pandoc](http://johnmacfarlane.net/pandoc/)):

    pandoc -f html -t markdown --no-wrap -o FILENAME.md FILENAME.html
    <commit_msg>fix GH Pages post layout<commit_after>---
layout: post
title: "Publishing with GitHub pages"
date: 2013-09-25 14:56
comments: true
categories: blog
share: true
tags:
- open-access  
- open-source  
- publishing  
- GitHub  
- Hybrid Pedagogy  
- FlipCamp  
- Engaging Students
---

This week, I helped the folks at [Hybrid Pedagogy](http://www.hybridpedagogy.com) publish [an ebook on open online learning](http://learnerexperiences.hybridpedagogy.com). Like [*Engaging Students: Essays in Music Pedagogy*](http://flipcamp.org/engagingstudents), and all of my course websites, we published it using GitHub's free web hosting option. I've written about [why one might want to use GitHub](http://hybridpedagogy.com/Journal/files/GitHub_for_Academics.html) for a project like this before, so this post will not explain why. Instead, I'd like to explain *how* for all those interested in this process, particularly those who want to pursue open-access or open-source academic publishing.

## Setting up a blank ebook ##

Since the ebooks I've built have essentially been websites, any host, platform, or design is fine. However, GitHub allows any public project—including websites—to be "forked," or copied for remixing and republishing. The easiest way to publish an ebook, then, is to fork an existing ebook and replace the content. I have a template anyone can copy ([source](http://github.com/kshaffer/GHbook) \| [site](http://kris.shaffermusic.com/GHbook)), or you can fork *Engaging Students* ([source](http://github.com/flipcamp/engagingstudents) \| [site](http://flipcamp.org/engagingstudents)) or the HP project, *Learner Experiences* ([source](http://github.com/hybrid-pedagogy/LearnerExperiencesInMOOCs) \| [site](http://learnerexperiences.hybridpedagogy.com/)).

## Google Drive ##

The content for both the FlipCamp and HP projects began with Google Docs. These are easy to produce, and they involve as much new technology as I am comfortable asking most people to wrestle with when submitting something to a publishing project. HP asks authors to compose articles in Google Docs and submit by sharing them with the editors; we used the same process for *Engaging Students*. *Learner Experiences* involved student essays which were uploaded to GDocs for the editing and publishing process.

## Exporting Google Docs for GitHub ##

Of course, GitHub will not simply publish Google Docs. GitHub can publish HTML pages, or it can use the open-source application Jekyll to convert any MarkDown or Textile files to HTML for web publication. And if you want to publish the ebook in ePub, Kindle, or PDF format, MarkDown is helpful there as well. So we want each article in a MarkDown file.

Google Docs does not support MarkDown. However, Google Docs can be exported in a number of file formats, which can in turn be converted to something GitHub can deal with. Each brings its own problematic aspect to that process, but I've found one almost ideal solution.

First, we exported all the Google Docs as HTML files.

Next, we converted those files to MarkDown, using the following code for each file (you may need to download and install [Pandoc](http://johnmacfarlane.net/pandoc/)):

    pandoc -f html -t markdown --no-wrap -o FILENAME.md FILENAME.html
    
{'fraction_non_alphanumeric': 0.07544560540872772, 'fraction_numerical': 0.0036877688998156115, 'mean_word_length': 4.563247863247863, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5996663', 'n_tokens_mistral': 1831, 'n_tokens_neox': 1710, 'n_words': 866}