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:
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 #
- For the old repository clone URL, use:
- Enter any name for your project.
- 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).
- Click on Begin Import and wait for it to finish.
How to find a repository’s URL
In this example, the template repository is located at publuv/textbook
To clone project which catch your interest, 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.
Authoring, committing, and file management #
All pages of the book must go inside the
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: for a personal project with only 1 author, select Commit directly to the
main branch and click Commit new file.
Uploading Markdown files #
To upload your files, go to Add File > Upload files
Uploading a folder #
You have to drag a folder from your file explorer into the box area.
Another way to create a new folder:
- Select Create new file.
- In the
Name your filebox, type in your folder name and
/, then type a placeholder file name like
- 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
│ └── topic1.md
To manually set the order of links inside the sidebar, inside
src folder, create a
SUMMARY.md file (must be all caps).
Then, 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
Although servers typically costs money, GitHub provides free hosting and support for public, open-source projects.
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 related topics on 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 (
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 designer is going to CTRL+F for
<< marks to find every single location where an image is supposed to be, and then place your 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.”
Markdown Editors #
While Markdown is touted for its simplicity, some people think the Wikipedia-like syntax is primitive and egregious.
However, when it comes to free editors and writing programs, you’ll have an easier time finding a Markdown editor.
For example, Zettlr has:
- Export to Word and PDF
- Zotero integration
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.
Once you are “in your own lane,” commit changes to your new branch instead of in the
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:
- Making an ebook — From Markdown to Kindle by David Grophland
- Convert Markdown to InDesign by Dr. Wouter Soudan
- Typesetting w/ Markdown and ConTeXt by Dave Jarvis
- Convert Markdown to Shunn Manuscript format
Book generators in the wild #
Here are some generators specific to making book websites:
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|
Used to create complex reports and notebooks for scientific research.
|Principles and Techniques of Data Science|
Create a fully-rendered Markdown page by pasting a snipppet at the end of the file and giving it a
|Ray Tracing in One Weekend by Peter Shirley|
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