The book feature is designed for knowledge sharing. It can be used to create multi-page content such as online courses, software documentation, knowledge bases, books, notebooks, and tutorials.
Did you know that this website was created from the Project Documentation template and uses the book layout for the purpose of documenting Wowchemy?
If you are creating a new site, check out the Project Documentation and Online Course starter templates which will help you get up and running fast.
Organization
The book feature can be used to create courses, tutorials, and documentation in the following file structure:
content/course
├── _index.md # Overview
└── intro # Chapter folder
├── _index.md # Chapter metadata including chapter title
├── example1.md # A page
└── example2.md # Another page
└── tutorial # Another chapter
├── _index.md
├── intro.md
└── ...
File and folder names should use hyphens instead of spaces, for example creating a course folder named my-course
.
The course
folder in the example above may be renamed. For example, we can rename it to book
for writing a book, docs
for software/project documentation, notes
for creating a notebook, or tutorials
for creating multi-page “how to” guides.
Metadata
Let’s edit a file using the book layout, for example _index.md
within your new folder (e.g. content/course/example/_index.md
), in order to specify a name and summary for your new book content.
# Page title
title: An Example Course
# Title for the menu link if you wish to use a shorter link title, otherwise remove this option.
linktitle: Course
# Page summary for search engines.
summary: Blah, blah, blah...
# Date page published
date: 2018-09-09
# Book page type (do not modify).
type: book
# Position of this page in the menu. Remove this option to sort alphabetically.
weight: 1
Menus
You can order your book menus in three ways:
- By title ascending
- By title descending
- By manual ordering using
weight: 10
in the front matter of pages, where the number defines the order- users recommend using weights that are increments of 10 so that it’s easy to reorder a page in the future without needing to change the weight of all the other pages
Pages
You can create as many pages as your need. Each page should have a title
, and a page type
of book
.
title
is the page title which appears in page header, whereas linktitle
is the label for link to this page. If you remove linktitle
, the menu link will display the page title.
To remove the right sidebar for table of contents (generated from the headings on your page), set toc
to false
.
To show a prev/next pager at the bottom of each docs section page, enable docs_section_pager
in params.yaml
and then set the order of the pager if you wish by defining a weight
for each page.
An example page is as follows:
---
title: Example Page 1
date: 2019-05-05
type: book
---
Content...
To list child pages on book chapter pages, you can use the {{< list_children >}}
shortcode.