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?
The book content type is new in Wowchemy v5.
For earlier versions of Wowchemy, the docs type can be used.
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.toml
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.toml
.
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 `static/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.toml
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.toml
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.toml`)
weight: 1
---
Content...