How to create an online textbook

⚠ Work in progress: I’ve realized this post really sucks and I need to improve it. For now it’s just a dump of information, but planning to make a video tutorial as well

Inspired by Creating Open-Access Web-Based Textbooks with GitHub, this guide is meant to be an easy and hands-off experience with publishing a textbook to the web, for free. It will let you practice sustainable authorship, expose you to static site generators, try Git as a collaborative tool, and understand why cloud computing is popular.

💡 At the end of this tutorial, you will have an online textbook that looks like:

The theme is generated by mdBook, and it comes with PDF print output.

How long does it take to publish a book? #

10-30 minutes, if you know what you’re doing. This is contigent on two things:

  1. Open Access
  2. Sustainable Authorship

Assuming that you adopt the authoring workflow of plain text (such as Markdown), and you’re willing to share knowledge for free, publishing takes 10 minutes. No joke.

Obviously, this time estimate doesn’t include the hard parts: writing the book, marketing the book, and providing value to an audience.

“My advice to young writers is to ignore dead trees publishers of all kinds. You don’t need a publisher to reach your audience. A Web server and worth-of-mouth is all that you need to reach an audience of 50 million. The time and effort that you put into schmoozing agents, editors, and publishers could be better spent practicing your craft.”
—Philip Greenspun, “Why I’m not a Writer”

Set up a repository for your book #

First, create an account at GitHub.

1. Make a new repository #

On your homepage, click on the New button on the left side, or the Start a project button under the beginner’s announcement for “Learn Git and GitHub”.

2. Click on Import a repository. #

If you made an empty repository, scroll down to the bottom of the screen and click Import.

3. Fill out repository details #

  1. For the old repository clone URL, use: https://github.com/publuv/textbook.git
  2. Enter any name for your project.
  3. Set the repository to Public (You may set it to Private, but GitHub’s service will have a monthly limit. See billing for GitHub Actions for details).
  4. Click on Begin Import and wait for it to finish.

How to find a repository’s URL

Go to the repo page and click on Code button at the right end of the view. Make sure the mode is set to HTTPS.
Code button dropdown shows the URLS for a repo.
In this example, the template repository is located at publuv/textbook

Authoring, committing, and file management #

All pages of the book must go inside the src folder.

Create your first page #

Click on the src folder, then go to Add File > Upload files

Name your file with a .md extension, then start typing Markdown into the editor.

When you’re done writing, select Commit directly to the main branch and click Commit new file.

Write in Markdown #

When it comes to free editors and writing programs, there’s plenty to go around.

For example, Zettlr has:

  • Export to Word and PDF
  • Zotero integration

Upload Markdown files #

You can create Markdown files on your computer and save them, then upload to GitHub.

To upload a file, go to Add File > Upload files

On the toolbar, click Add File > Upload Files

Uploading a folder #

You have to drag a folder from your file explorer into the box area.

On the toolbar, click Add File > Upload Files

Another way to create a new folder:

  1. Select Create new file.
  2. In the Name your file box, type in your folder name and /, then type a placeholder file name like temp.md.
  3. Once the folder is created, upload files as usual.

Arrange Table of Contents #

By default, the project will order your pages alphabetically/numerically.

  • First-level pages will go at the beginning, as frontmatter.
  • A first-level folder will render as a section title.

Example ToC and corresponding Folder Structure

src/
├── chapter_1.md
├── chapter_2.md
├── digital-authorship.md
├── easy.md
├── folder1/
│ └── topic1.md
└── ztitle.md

Manually set order #

  1. Inside src folder, create a SUMMARY.md file (must be all caps).
src/
├── SUMMARY.md
├── chapter_1.md
├── chapter_2.md
...
  1. Follow the SUMMARY.md formatting guidelines.

Host your book on GitHub Pages #

Go to the repository Settings tab, then Pages on the left navigation menu. If you’ve already committed changes, GitHub pages may be activated already! In that case, you can visit your website immediately.

Otherwise, select the gh-pages branch and /(root) folder, then click Save. Wait a few minutes for the GitHub domain to propogate.

GitHub pages allows you to host static wesbites (websites without a database).

Cloud computing means to use someone else’s computer to do stuff for you.

The textbook template uses GitHub Actions, a cloud computing service (more specifically, a DevOps service), to generate a website based off the Markdown files inside your src folder.

Although servers typically cost money, GitHub provides free hosting and support for public, open-source projects.

Takeaways #

This concludes the guide. It went over how you can freely host your book, and also how writing in Markdown makes it easier when it’s time to publish.

Converting Markdown to another format, like HTML, EPUB, Word’s DOCX or InDesign’s ICML is predictable and consistent. If you start writing in Word, you cannot guarantee that you’ll keep your styles when you convert to HTML or EPUB, and publishing houses don’t want styling anyway.

However, there’s a learning curve when it comes to data formats and all the ways you can self-publish. It’s perfectly fine to stick with mainstream tools such as Scrivener and MS Word.

Up next are topics related to internet and web publishing.

Open Access Movement #

According to the Universal Declaration of Human Rights:

Everyone has the right to education… Technical and professional education shall be made generally available and higher education shall be equally accessible to all on the basis of merit.

In academia, professors and researchers volunteer their time to peer review for journals. Peer review is considered a scholarly duty. No one is exempt from performing this act of community service if they want to advance their tenure and build up a reputation.

Then, journal publishers charge you to read scholarly submissions, regardless of which university you come from, or how many countless hours of free work you’ve offered.

Take a look at The Cost of Knowledge, a petition against shady and exploitative business practices damaging the scholarly community.

Sustainable Authorship #

Write each chapter as a Markdown file (.md extension).

Markdown can be written anywhere: in Google Docs, in Notepad, in MS Word, on your napkin. Markdown follows text chat conventions, such as using asterisks to denote emphasis, and it can be used in modern applications when writing Reddit, Slack, Discord and MS Teams comments.

As an author, writing in Markdown alleviates you from formatting concerns. Authors should only be responsible for raw content.

Since Markdown is simple, it’s easier to convert to Markdown to any higher-level format, such as MS Word, InDesign, EPUB for ebooks, HTML, and PDF.

Paragraph indents, page breaks, image inclusion and other such nuisances are a publisher’s responsibility. In fact, publishers want you to submit a manuscript as plain as possible, without any images embedded. They want images to be sent as a separate zip file. In your manuscript, you must reference image placement with some kind of syntax like:

<< photos/26.jpg >>
<< Caption: Toenail at 5000x magnification >>

A graphic designer will comb through the manuscript and insert images as they think looks best.

In Markdown, there is already a syntax for referencing images:

![Toenail at 5000x magnification](photos/26.jpg)

If an editor reads this line, they would understand what you mean. In lieu of a traditional publisher, automatic book generators would also know how to render the image on a website.

"When you use MS Word, Google Docs, or Open Office to write documents, what you see is not what you get. Beneath the visible layer of words, sentences, and paragraphs lies a complicated layer of code understandable only to machines. Because of that hidden layer, your .docx and .pdf files depend on proprietary tools. Such documents are difficult to search, to print, and to convert into other file formats.

"Moreover, time spent formatting your document in MS Word or Open Office is wasted, because all that formatting is removed by the publisher during submission. Both authors and publishers would benefit from exchanging files with minimal formatting, leaving the typesetting to the final typesetting stage of the publishing process.

“This is where Markdown shines. Markdown is a syntax for marking semantic elements within a document explicitly, not in some hidden layer… Writing in this way liberates the author from the tool. Markdown can be written in any plain text editor… For this reason, Markdown is currently enjoying a period of growth, not just as as means for writing scholarly papers but as a convention for online editing in general.”

Sustainable Authorship in Plain Text using Pandoc and Markdown

Branching with multiple collaborators #

When you are about to commit a file, you can opt to Create a new branch for this commit and start a Pull Request. This option will create a new branch. You can make changes on a new branch without affecting the current version.

Select the new branch by clicking on the branch menu, which has a pronged icon.

Menu showing all branches

Once you are “in your own lane,” commit changes to your new branch instead of in the main one.

When you have multiple authors, it is easier for each author to work on their own branch. Eventually, an approver should merge changes to the main branch, making a draft become part of the final.

The concept of branching and Pull Requests takes some time to familarize with. If you are serious about collaborating on a complex document with multiple authors, try the GitKraken client to make it easier to sync repositories and track branches.

Advanced formatting #

For actual print books you may want to look into these options:

Book generators in the wild #

Here are some generators specific to making book websites:

GeneratorExample
Bookdown
An open-source R package that facilitates writing books and long-form articles/reports with R Markdown.
On The Line: How Schooling, Housing, and Civil Rights Shaped Hartford and its Suburbs by Jack Dougherty
Jupyter
Used to create complex reports and notebooks for scientific research.
Principles and Techniques of Data Science
Markdeep
Create a fully-rendered Markdown page by pasting a snipppet at the end of the file and giving it a .html extension.
Ray Tracing in One Weekend by Peter Shirley
mdBook
Fast, cross-platform generator with a working theme out of the box.
The Rust Programming Language

There are tons and tons of advanced generators, which are called Static Site Generators, available in any programming language.


Photo by Julia Volk