becarpenter-book6/99. Chapter Template/99. Chapter Template.md

# Chapter Template

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](https://github.com/becarpenter/book6/blob/main/CONTRIBUTING.md) 
and [LICENSE](https://github.com/becarpenter/book6/blob/main/LICENSE.md)
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 [<ins>Markdown Usage</ins>](Markdown%20Usage.md) 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:

```
  # Chapter Template
```

so that makes three repetitions of `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](../Contents.md) page.

It does some other things as well, to help authors:

1. 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 Stuff` at the obvious place in Contents.md would
   work.

1. 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.

1. 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.

1. 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.

1. It expands certain references, as explained in
   [Markdown Usage](Markdown%20Usage.md).

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](https://github.com/becarpenter/book6/blob/main/utilities/chapterReorg.md).

## [First Section](First%20Section.md)

## [Section Template](Section%20Template.md)

## [Markdown Usage](Markdown%20Usage.md)

## [Last Section](Last%20Section.md)

### [<ins>Back to main Contents</ins>](../Contents.md)