Create a course, documentation, or book

The book feature is designed for knowledge sharing. Use cases include online courses, books, notebooks, tutorials, software documentation, and knowledge bases.

Did you know that this website is using the book layout for the purpose of documenting Wowchemy?

Continue reading below to learn more about creating multi-page content using the book feature.

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

# Academic 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
  • 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 in 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.

Create a course or book (in v4)

The legacy docs feature is designed for knowledge sharing. Use cases include online courses, tutorials, software documentation, and knowledge bases.

For users with existing docs content, continue reading below to learn more.

Organization

The docs feature can be used to create courses, tutorials, and documentation in the following file structure:

content/courses
├── _index.md         # Lists your courses, tutorials, or documentation
└── example           # Folder for your course/tutorial/documentation
    ├── _index.md     # Overview of this course/tutorial/documentation
    ├── example1.md   # A page
    └── example2.md   # Another page
└── course2           # Folder for another course/tutorial/documentation
    ├── _index.md
    ├── intro.md
    └── ...

File and folder names should use hyphens instead of spaces, for example creating a course folder named my-course.

Renaming

The courses folder may be renamed. For example, we can rename it to docs for software/project documentation, or tutorials for creating an online course.

After renaming or deleting the courses folder, you may wish to update any [[main]] menu links to it by editing your menu configuration at config/_default/menus.yaml.

For example, if you delete this folder, you can remove the following from your menu configuration:

[[main]]
  name = "Courses"
  url = "courses/"
  weight = 50

Or, if you are creating a software documentation site, you can rename the courses folder to docs and update the associated Courses menu configuration to:

[[main]]
  name = "Docs"
  url = "docs/"
  weight = 50

Listing courses and books

The content/courses/_index.md file automatically lists any course, tutorial, or documentation folders within the content/courses/ folder. Open the file to edit the page title.

title: Courses
layout: docs  # Do not modify.

# Optional header image (relative to `assets/media/` folder).
header:
  caption: ""
  image: ""

Course and book metadata

Edit the _index.md within your course/documentation folder (e.g. content/courses/example/_index.md) in order to specify a name and summary for your course/documentation.

# Course title, summary, and position in the list.
linktitle: An Example Course
summary: Learn how to use Academic's docs layout for publishing online courses, software documentation, and tutorials.
weight: 1

# Page metadata.
title: Overview
date: "2018-09-09T00:00:00Z"
lastmod: "2018-09-09T00:00:00Z"
draft: false  # Is this a draft? true/false
toc: true  # Show table of contents? true/false
type: docs  # Do not modify.

# Add menu entry to sidebar.
# - name: Declare this menu item as a parent with ID `name`.
# - weight: Position of link in menu.
menu:
  example:
    name: Overview
    weight: 1

Menus

If you use the docs layout, note that the name of the menu in the front matter should be in the form menu: X: where X is the folder name. Hence, if you rename the courses/example/ folder, you should also rename the menu definitions in the front matter of files within courses/example/ from menu: example: to menu: <NewFolderName>:.

Hugo also offers an alternative approach of storing the menu for each course/documentation centrally in config/_default/menus.yaml rather than in the front matter of each course/documentation page.

Read more about Hugo’s menu system here.

Pages

You can create as many pages as your need. Each page should have a title, menu link (menu) to it, and a page type of docs.

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 show a table of contents generated from the headings on your page, set toc to true.

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 by defining a weight for each page.

An example course/documentation page is as follows:

---
title: Example Page 1
linktitle: Tips 1-2
toc: true
type: docs
date: "2019-05-05T00:00:00Z"
draft: false
menu:
  example:
    parent: Example Topic
    weight: 1

# Prev/next pager order (if `docs_section_pager` enabled in `params.yaml`)
weight: 1
---

Content...