Chapter 1 Creating a new book from scratch

1.1 Creating a new repo for a new book on Github

NOTE: This guide assumes you already have the ability to work with Git repositories on Github, including checking out repos, as well as making and pushing commits. (Also, if you are not a power user of Git, we recommend Github’s desktop tool. It makes it simple to work with repos without memorizing command-line syntax, and it handles most simple scenarios.)

Go to our empty book repo on Github and click “Use this template.” (You must be logged into Github already.)

Change the owner to warhornmedia. Enter a repository name using the format “authorlastname-short-book-title”. Set the repository to public. And include all branches. Then click “Create repository from template”

Clone the new repo to your computer and begin making changes

Congrats! You now have a new book that will rebuild automatically any time you push changes to github.

Your next task will be to update all of these files, and then to add the book content. You will find this information in the following sections.

1.1.1 (Optional) Preparing and using a local build environment

Being able to build a book locally can save time so you don’t have to wait for the book to be rebuilt by continuous integration. Typically a local build is done in under 10 seconds, and an online build takes 2-3 minutes. This can really add up if there is a problem you are trying to fix through trial and error.

Instructions:

Download RStudio for desktop here.
Make sure that LiberationSerif is installed. (TODO: When we finalize fonts, this will need to be updated. It’s possible it’s already out of date.)

Now you can open the file that ends in .Rproj, and you should be able to click “Build Book” in the “Build” tab in the upper right.

A note on classics-template-files: When you first build the book locally, a new folder will be created in the book folder called classics-template-files. These files come from a separate repository by the same name. They allow us to make changes to the style and front matter of every book from one central location. But once you have these files in your local book folder, they will not be updated with new changes to the design unless you delete the whole classics-template-files folder. (This folder is excluded from tracking git, so you don’t need to worry about deleting it or updating it before committing changes to the book.) Thus, if you have not worked on a book for a while, it makes sense to delete this folder from your local book repo before you next work on it.

1.2 What are all these files?

Below is a list of the files in the book template, along with a description of that file and the contents. If the name of a field inside a file is bold below, that means you need to customize that field for a new book.

1.2.1 Files you must modify

01-Basic-instructions.Rmd

Contains the content of the first chapter of the template book. Should be deleted or renamed and its content replaced with the first chapter of the new book. See

_bookdown.yml

contains some settings for bookdown.

Contents:

book_filename: Change this to give book downloads, such as PDFs, appropriate filenames. Don’t use spaces. Standard: author’s last name followed by short title, like so:
book_filename: "Ryle-Duties_of_Parents"

Don’t change anything else in this file, unless you need “chapters” to be called something else. If so, make sure you check all the output formats thoroughly and report back. This is currently untested in our books.

_editorial-notes.Rmd

Contains two sections that must be updated throughout the editorial process, and is automatically included in the front matter of the book.

Contents: :

Text Status This section should be updated by moving the “Current status: –>” to the front of the appropriate line as the project progresses. :

Editorial Notes Any noteworthy editorial decisions should be added to this section.

cover.jpg

Should be replaced with an image of the book cover. Alex is working on a simple design that will be able to be used for all of the books. Both JPG and PNG files are supported.

index.Rmd

Contains many settings for the book and the code to automatically include the Classics front matter in each book. Anything not mentioned below should be left unchanged.

Contents:

title, author, and date must all be changed and should be self-explanatory

description: Short description of the book. Don’t use copyrighted content here. Write your own description. This field is useful for SEO. Also, it is displayed together with the cover image when the book is shared on certain social media.

params:

pubinfo: This appears in the front matter and should be updated with the original publication info.

scans: Enter a link to scanned images of the original public domain work on Archive.org, Google books, or elsewhere.

build: This can be any number. Change the build number if you ever want to force the book to rebuild but haven’t changed anything else. It’s used for no other purpose.

cover-image: the name of the image file being used as the cover for the book. Make sure to include the extension, such as cover.jpg, or cover.png.

url: the page where the book is hosted. Should be https://warhornmedia.github.io/your-new-github-project-name/ Replace the last part with your project name. Currently that ending “/“ is necessary.

output:
- bookdown::gitbook:
  - config:
    - toc:
      
      before: This content is shown above the TOC on the web version of the book. Having the book title (and author last name if it will fit), is helpful for people to know what they are looking at. Change this on the second line.
    - edit: where the edit link on each page points to. Should be the GitHub project URL, followed by “/edit/master/%s”

README.md

The description of the repo that will be displayed on the Github project page. Update this with some simple info and a link to the readable book.

1.2.2 Other files

_output.yml

Contains a number of settings for the various output formats. You generally shouldn’t need to make changes to this file. However, you can modify the following line to add or remove links to the various formats if necessary. For example, if the PDF won’t build or has problems, simply remove it from the list. Or you can add kfx to the list. Other formats might be possible as well.

```
download: ["pdf", "epub", "mobi"]
```

book_project.Rproj

This file can be ignored. If you use the Rstudio IDE, this is your project file, and you’ll probably want to rename it to the book title just so you don’t get confused which book project you are working on.

.github folder

contains the Github Actions workflow file that rebuilds the book automatically every time a new commit is pushed to Github. You shouldn’t need to mess with this folder. In fact, it is a hidden file, so you normally won’t see it at all unless you are working on the command line or Github.

.gitignore

Specifies which files are not to be tracked in git. In particular, we only want to track book source, not output files (_book), files related to RStudio, or external files used in the build process (classics-template-files). This file already has the right settings. You shouldn’t need to mess with this file. In fact, it is a hidden file, so you normally won’t see it at all unless you are working on the command line or Github.

1.3 Adding book content

To add content to the book, simply add .Rmd files. .Rmd files are just text files written in R-markdown. R-markdown is just normal markdown with some extra features supported. The details of the features we support are outlined below. (TODO: We should probably add to this documentation the basic rules about how we want our markdown formatted.)

Note: The filename must end with .Rmd, not .md, if you want it included in the book. That is why the README.md file is not build into the book.

All the markdown files found in the main directory will be combined into a book, ordered by filename. So use numbers at the beginning of the files to indicate the order they should go in. Note that index.rmd will always come first, though, and will automatically include the Warhorn Classics front matter.

To exclude a file from the book, simply preface the filename with an underscore. For example, “_excludedfile.Rmd” will not be added to the book by default, even if it is in the main directory with all the other Rmd files.

Here is an example list of files in the order they will end up in the book.

index.Rmd
00-preface.Rmd
01-The-Sacraments-In-General.Rmd
02-The-Sacrament-of-Baptism.Rmd
03-The-Sacrament-of-the-Lords-Supper.Rmd

Note that the numbers at the beginning of each filename are only used to get the files into the proper order in the book. It is handy if they can correspond to the chapter number just to prevent confusion, but it is not necessary.

The online version of the book will be split up into separate pages, not just one long web page. The split will happen at each new .rmd file.¹ Thus, in most cases a new .rmd file should be created for each chapter.

NOTE: Each .rmd file must begin with the title of the chapter (or section) it contains. (The proper syntax is described in the next section.)²

1.4 Chapters, sections, and more

The primary structure in Warhorn Classics books is determined by various levels of headers, and it can easily be seen in the automatically generated table of contents.

By default, the top level of structure is called a “chapter.” However, this word can be changed in _bookdown.yml if necessary for sermons or other types of works where “chapter” is not appropriate.³

The start of a chapter is specified in the text with a # followed by the title of the chapter. Here is an example of the proper syntax:

# A Long-expected chapter title

The chapter title will be given an <h1> tag in HTML, with similar results in other formats.

Chapters can be broken down further into sections, sub-sections, etc. up to 6 levels total, using additional levels of headers and titles:

## This is a section. (It will receive an <h2> tag in HTML.)

### Here is a sub-section.

#### And now a sub-sub-section

###### This is the deepest level supported, because <h6> is the deepest header level supported in HTML.

1.4.1 Numbering (or not)

Chapters, sections and subsections will all be automatically numbered, unless you exclude them from numbering by adding “{-}” to the end of the line. For example, generally an introduction should not be numbered:

# Introduction {-}

Text of the introduction goes here...

Or perhaps the subsections in the book are not numbered:

# How to write a book

## Getting started

### Arranging your pencils {-}

It is possible to assign an ID and specify that a section is not to be numbered like so:

## Section forty-five {- #sec-45}

1.4.2 IDs

Chapters and sections always have an ID so they can be linked to. If one is not set explicitly, one will automatically be given (implicitly) based on the title. This will be discussed later in the references section.

This can be changed, if necessary, to split by chapter or section, or even turned off completely.↩︎
Supposedly the first file must begin with either a chapter (“# Chapter name”) or a section (“## Section title”). However, it appears that it must be a chapter, as starting with a section causes an error. Latter files may start with a section, instead, if necessary, to split the book into appropriate-length webpages.↩︎
The bookdown documentation says it is also possible to split a book into “parts” made up of multiple chapters, as well as add a special “part” called “appendix.” However, ebooks and Word documents do not get any “part” information, so we do not support this option in our books.↩︎