`ghc` Command to Create Textbooks in GitHub Classroom with TOC

Still a major work in progress but loving our ghc (GitHub Courses) command to automatically update the main README.md files as well as the course.json file for eventual inclusion in some kind of searchable course manager. Enjoy and let me know via issues of suggestions etc.

Here’s the repo

Will post samples as I complete the migration. Love that GitHub has become the platform for textbooks of the future.

1 Like

Interesting concept! Just a couple of things I’m wondering about in your blog post:

By making the default branch gh-pages and removing the master branch for your workbook starter repos you can allow students to use the work repo for web development and just use GitHub Pages free hosting if you don’t have another method of allowing students to host their own web content. By making the starter work repo private you also hide student work from others who might otherwise just find it online.

This seems a bit problematic to me, since all Pages, even those on private repos, are public by default.

Another consideration is what is visible in the workbook repos to students. Often—especially with beginners—you don’t want anything in there that they cannot easily figure out. They will experiment with whatever you put in there, such as starter libraries or commands. The easiest way I have found to avoid this is to create hidden directories, .bin instead of bin, .lib instead of lib. This works best on a multiuser system on which you control at least a portion of the setup so you can add these hidden locations to the relevant paths.

How does this work on Windows, which doesn’t use the dot prefix to hide files/directories?

Hi Samuel,

I really like that even private repos are public through student’s web site. To me using gh-pages isn’t security to prevent students from seeing each other’s work, it just keeps it from being directly seen as would be in a student’s own repo.

In the case of Python, for example, I put the textbook repo on gh-pages just so the resources can be linked from other web sites and such and the workbook is on the master branch.

For the web class I will have it on gh-pages because students could see each other’s content no matter what.

As for the Windows question I would look into a way to provide the same thing in a workbook repo for Windows. We use the bash command line for everything and even on Windows this hides the dotted files. It might help to know I’m coming at it from that angle. We don’t use Python IDLE or any other IDE or even editor other than vim on the command line. Love to hear what you come up with for alternative approaches. This is just ours.

Thanks for the response.

By the way, I just added automatic TOC creation to every part/section page as well, automatic footer addition, and summary parsing to the automatic course.json creation.

I’m curious: why are your creating your own tools, instead of using a service like GitBook (https://www.gitbook.com/)?

I like GitBook for what it was designed for, producing books, but traditional books have little or no value in most modern tech education today. Many won’t like hearing that, but it is just the truth. The sooner we accept it the better for everyone.

For example, animated GIFs cannot be included in books. These have become defacto standards for all learning material. Modern students really respond to them. Most modern web services provide tutorials using them. When longer video is needed GitHub allows it to be linked directly (although not embedded). None of this is possible with GitBook.

Another reason is that student and collaborator contributions to the material are not immediately obvious. This way creating an issue for a spelling error is literally a click away. Also, contributors to the material are rewards with contributor credit in the commit history. While this is possible using GitBook, the very idea of GitBook is taking the Git out of the Book. I’m sort of celebrating it and promoting it as a way to maintain the information.

Using a GitHub Textbook and Workbook model also allows code and other structures to be created that GitBook would completely ignore. For example, in our Python Fundamentals Workbook starter repo I can link directly to source as well as provide a personal, private copy of any dependencies (libraries, etc.). None of this is even in the scope of GitBook.

GitBook is also yet another step in the production workflow that is all together unnecessary. When considering the reasons for having a GitBook, and all I can think of is actually publishing a book or e-book, then the main reason for that extra work doesn’t serve our approach, in fact, any book that cannot be instantly updated is inadequate.

In many ways, the ghc helps me make Books in Git instead of from Git.

As a educator myself (CS teacher in a French engineer school), I tend to disagree with your dismissal of books in modern tech education.

Compared to a set of interdependent GitHub repos, a book provides something very important for students: structure. It is still the ideal format for real content. I’ve experimented with GItHub-based class material (example - sorry it’s in French) but as soon as my content outgrows a few lines of text and some external links, I come back to writing a book.

A book built with GitBook upon a public GitHub repo provides contribution history, allows for pull requests, etc. Best of both worlds.

On the other hand, raw GitHub + Classroom is GREAT for distributing assessments and supervising student work.

Well I did say I expect most will disagree with me, but that’s ok, I’m used to it.

Which is the whole point of ghc such as the prep.skilstak.io course we just converted over and the pyfun.skilstak.io course I am working on converting now. Did you look at it? It is a proof-of-concept hack at the moment, but provides exactly the structure my students need. I don’t expect most of the rest of the educational world will see its value, but I’m also used to that. :grin:

I’d argue that the GitHub texbook/workbook model provides accessible structure. I watch these young kids learn to search for everything—especially now that things like Mac Spotlight exist. No one uses the Finder anymore. While GitBook does provide some of this, it doesn’t get them to what they need and it is also not searchable from the command line as easily.

The up and coming generation does not use books even though they might read a ton. Unless it is a novel (graphic or otherwise) it is very rare. I’m not commenting on what I think of that, only that it is the reality.

I choose to raise students fully proficient in most advanced, professional tools and workflows and GitBooks ain’t one of them. GitHub, on the other hand, is something they will use daily, if not hourly. The more I can maintain my workflows for the whole school using GitHub workflows the better. I have 10 year olds opening issues with custom labels on the textbook to suggest corrections as well as let me know when their workbook assignment is done. Show me how you are doing to teach those skills from a GitBook or any other book. I prefer to integrate these processes and teach them so they are fundamentally second nature to my students, and guess what, it works.

I believe as much as you in OER and text-based, Git-versioned class material. This is the future.

The workbook part of your approach is convincing. It lets students learn the GitHub workflow, is cleanly automated via Classroom, and make them feel empowered along the way. OK with me.

I’m less convinced about the textbook part. I don’t see any game-changing advantages in publishing teacher-created, teacher-maintained (let aside the occasional typo fix) resources directly via GitHub. However, ugly SEO-unfriendly URLs, visual GitHub clutter and lack of navigation are some pretty major flaws, at least for me.

A GitHub-powered GitBook can be read online confortably, downloaded as PDF or ebook, viewed directly on GitHub and edited instantly the GitHub way. It is as much an OER as your textbook repo.

To each his own, I guess.

SEO is a compelling argument. It was the hardest one to let go of when moving our material from single-page-app-ish stuff. The GitHub clutter is also tough to swallow—especially when I have non-technical parents using it who might be confused by it. Another negative is load time. GitHub repos load considerably more slowly than a web site. Then there is the utter lack of the ability to put any of the textbook into a proper CDN.

All of these are cons that would promote the creation of a web version of the GitHub content, but never a GitBook, for me. It might seem like a small thing to most, but animated GIFs are fundamental to tech instruction today. I should blog just about that. I can put an animated GIF of a process on the big screen and have it loop over and over while I walk around helping students through the process. Before I had to repeat the process myself several times “at the board” because they missed one or more steps.

There was a time I would have ROFLing at that statement about using GIFs myself, but it is just true these days. Zenva tutorials, Lynda.com, and so many others use them. If GitBook supports animated GIFs I imagine the PDF, ebook, and other products would not.

What I would really like to see is a standard course GitHub repo format that could be used to generate sites, pdfs and whatever else. I have started to generate a course.json file for inclusion in our own searchable registry, but I think the format for a course needs to be outside of any one specific implementation. For me simple READMEs organized in a standard way, with information in the course.json file indicating organization to any particular course packager is ideal.

Eventually I do hope to create a SPA generator for each course and by following standards such as these automating that won’t be hard. The SPA will then be downloadable as an app or otherwise for classroom iPads and such.

Still, I love being able to tag and version a textbook and inform students how to use the different versions. This is particularly important for material that changes rapidly because the workbook can be tagged with the version of the textbook it used. This could be done with GitBook as well.

The main reason I won’t be using GitBook anytime soon is simply because of the extra step to set it up for each textbook and being forced into a format I don’t particularly agree with that is designed for one and only one use, GitBook. I sense there is something else better our there, either already built or available to be built. The good news is that we are really exploring this in ways that will disrupt the status quo forever. Good job GitHub!

I should mention that whatever ends up coming of this should have a tags or concepts notion for each section so that they can be gathered together into an index if not a summary on the TOC. GitBook does not offer this currently.

I wholeheartedly agree with you on the need for a standard GitHub course format with a special view mode, easy navigation, cross-linking, etc. This would be the ideal solution. I’d drop GitBook in a heartbeat the day this comes out.

The importance of animated GIFs and tags hasn’t crossed my mind before. I’m gonna experiment a bit in these ways.

Thanks for the interesting discussion.

As a Haskell nerd, just want to throw out a suggestion for a rename of the command!

ghc is the Glasgow Haskell Compiler, the dominant compiler for the Haskell programming language, developed at Glasgow University. It’s command is ghc, and it’s used in quite a few universities for intro to programming, intro to functional programming and intro to programming language theory.


So it may cause some issues for quite a few lecturers who want to use your command! (Which looks excellent, by the way!)

Thanks for the heads up Joe. Happy to change the name to something else, any suggestions?

That utility has been nice and served us well for the moment but in the process of writing course materials I have uncovered a bigger problem involving redundancy in educational materials, which sent me creating something we call the Skills Package Manager to manage the content for learning a skill in much the same way that software is managed through packages with individual skills and topics being essentially functions and methods that are effectively required together in markdown files to create, what we call, a compiled content build for a given lesson or project. It feels a lot like coding human brains the way you would code a computer. We then changed the name to Skills Builder (skb) and are still working on that.

As things happen, in the process of building skb to build educational, consumable, customized content I realized the tool itself could be worked into a web browser of sorts that focuses on pulling in content on demand and including it inline in the document rather than linking out to it. We see this idea a lot already with social media lazy loading and such. A browse content session would then dynamically create a very personalized, consumable artifact with just a Save function, even Save as PDF, or Save as PWA or Save as GitHub Repo (which is effectively what ghc does now). These artifacts are the “Textbooks” I was seeking in all of this. Highly fluid, versioned, and updatable in a way other educational media could never keep up with.

The more I looked at how such a tool could work and the fact that the instructor would still be creating the artifacts and distributing them to the student users the more I wondered if we could even remove that step and have students create their own consumable, educational content resources, their own textbooks and workbooks.

Then it REALLY hit me.

Having been around since before there was a world wide web and watching it be born of a desire for scientists to allow peers to both consume AND create content that could be easily linked together I realized the very approach to consumer and creator content sharing has been lost and yet the skb tool I was building to dynamically create documents of shared content by including and loading rather than linking might just be an entirely new way to approach the world wide web itself.

The Essential Web

The Essential Web is the term my college-age son, wife and I came up for this very exciting concept. I still find myself jumping up and down with exuberance about the potential this could have and have begun capturing the key ideas and thoughts about it in a repo for now that eventually the essentialweb.org will point to. I got the domains and am preparing a site for explaining the concept. The content there is literally being written right now as we work out the details of what could be one of the most important standard specifications the web has seen in years, albeit approachable and doable.

I would really, really love the input about the Essential Web spec from other technical professionals and educators, who have a particular propensity for being both good technical people as well as good writers.