This chapter shows how to write a new chapter. It is intentionally listed in the contents of the book itself, and is intended to be a living chapter of a living book. You should also check CONTRIBUTING and LICENSE before contributing.
The second section in this chapter shows how to write a new section.
We use the GitHub dialect of Markdown. There is some information about this in the Markdown Usage section below, including how to include diagrams.
A chapter lives in its own directory, e.g. this chapter lives
in the directory 99. Chapter Template. Of course, the spaces
are part of the directory name and the name is case-sensitive.
The introduction to the chapter (like this file) is a markdown
file with the same name again, e.g. 99. Chapter Template.md.
The first line in this file is:
# 99. Chapter Template
so that makes three repetitions of 99. Chapter Template.
Start with the general intro for a chapter. Tell the reader what the chapter is all about. Then give a list of the sections. It would be possible to embed the sections right here, but maintenance by multiple authors will be easier with a separate file per section. So write the introductory text and then add a list of sections that you intend to write. For example, after the introduction, put:
## First Section
## Section Template
## Last Section
Please keep the section names short. They are also used as filenames.
The text of the section Section Template will be in a file called
Section Template.md.
Please do not add text inside or after the list of sections. That will confuse everybody.
Important: Markdown can't handle file names with spaces in them. When creating links, we have to replace spaces with %20, or avoid spaces in the file names. So here is the template for the list of sections after inserting links:
## [First Section](First%20Section.md)
## [Section Template](Section%20Template.md)
## [Last Section](Last%20Section.md)
That's a bit complicated, and since file names are case-sensitive, errors are easy to make. Therefore, there exists a Python program called makeBook, which can be run occasionally to create such links automatically, and reconcile differences between the actual chapter contents and the main Contents page.
It does some other things as well, to help authors:
-
If it finds a chapter in the main contents, but there is no corresponding chapter directory, it creates the latter with appropriate template files that the author(s) can edit. So adding
25. Interesting Stuffat the obvious place in Contents.md would work. -
If it finds a section in a chapter introduction, but there is no corresponding Markdown file, it creates such a file. The author only has to add the content.
-
If it finds a Markdown file in the chapter directory, but it's not in the chapter contents, it adds it to the list of contents.
-
It automatically inserts links at the bottom of each section pointing to the previous and next sections (if they exist) and back to the chapter introduction.
-
It expands certain references, as explained in Markdown Usage.
makeBook has to be run on the main Github branch from time to time. At this writing, there is limited practical experience with this - patience, please. If it goes wrong, there is nothing that can't be fixed manually. The main rule is: don't mess with the automatically generated links.
So, to repeat: add a new ## item to the chapter introduction, and makeBook will create the necessary .md file. Add a new .md file to the chapter directory, and makeBook will add it to the chapter contents.
Pro tip: Adding a new chapter, renaming or deleting a section or chapter, or moving a section from one chapter to another, etc., are not automated at present and may require a good deal of manual work. For that, see the special instructions.