README.md in jekyll-theme-gitbook-0.0.3 vs README.md in jekyll-theme-gitbook-0.0.4
- old
+ new
@@ -32,11 +32,11 @@
### GitHub Pages
If you are hosting your site on GitHub Pages then add the following line to your site's `_config.yml` file (as per [the documentation](https://docs.github.com/en/github/working-with-github-pages/adding-a-theme-to-your-github-pages-site-using-jekyll)):
```yaml
-remote_theme: "adamrehn/jekyll-theme-gitbook@v0.0.3"
+remote_theme: "adamrehn/jekyll-theme-gitbook@v0.0.4"
```
### Other hosts (e.g. GitLab Pages)
If you are hosting your site using a service that permits the use of Gem-based themes then add the following line to your site's `Gemfile`:
@@ -66,12 +66,21 @@
# The name of the Jekyll collection that contains the site's chapters (REQUIRED)
collection: "categories"
- # Specifies whether navigation links should be generated for chapter index files that use the `chapter-index` layout (OPTIONAL, defaults to false)
- indices: false
+ # Navigation menu settings (OPTIONAL, only needed if you want to override the defaults)
+ navigation:
+
+ # Specifies whether navigation links should be generated for chapter index files that use the `chapter-index` layout (OPTIONAL, defaults to false)
+ indices: false
+
+ # Specifies whether the navigation links for each chapter should be output as collapsible sections using HTML <detail> tags, with chapter headings as <summary> tags (OPTIONAL, defaults to false)
+ collapsible: false
+
+ # When collapsible sections are enabled, specifies whether sections are collapsed by default (OPTIONAL, defaults to false)
+ collapsed: false
# Copyright settings for the page footer (REQUIRED)
copyright:
@@ -126,11 +135,16 @@
Each key in this structure serves a specific purpose:
- `collection`: the theme uses a book metaphor to describe the structure of content. The site is broken down into a series of "chapters", each containing a series of pages. Of course, this naming convention does not make sense for all sites (for some sites, the "chapters" may in fact be referred to as sections or categories) and so the theme does not force you to adopt the name "chapters" in your filesystem structure. Instead, you can specify any [Jekyll collection](https://jekyllrb.com/docs/collections/) to act as your list of chapters, typically using one subdirectory per chapter to group pages. **You must specify the name of the Jekyll collection as a string value for this key.**
-- `indices`: by default, the theme only generates navigation links to each of the pages in each chapter, not to the chapter indices themselves. You can set this key to `true` if you would like to trigger the generation of chapter index navigation links, although note that links are only generated for chapters whose `index.html` files use the `chapter-index` layout and not for chapters whose index use the `chapter-redirect` layout. **This key is optional.**
+- `navigation`: this key groups settings for overriding the behaviour of the site's navigation links. **This key and all of its subkeys are optional:**
+
+ - Subkey `indices`: by default, the theme only generates navigation links to each of the pages in each chapter, not to the chapter indices themselves. You can set this subkey to `true` if you would like to trigger the generation of chapter index navigation links, although note that links are only generated for chapters whose `index.html` files use the `chapter-index` layout and not for chapters whose index use the `chapter-redirect` layout.
+
+ - Subkeys `collapsible` and `collapsed`: these subkeys allow you to make the sections of the navigation menu for each chapter collapsible, and specify whether they are collapsed or expanded by default, respectively.
+
- `copyright`: this key groups settings related to the copyright notice that appears in the footer of all pages. **This key and the `author` and `year` subkeys are required,** whilst the `license` subkey is optional.
- `logo`: this key overrides the default path to the site's logo image, which will be displayed in the header of all pages. Although the default value uses an `.svg` file extension, the logo image can be in any format supported by a web browser, it does not need to be an SVG file. **This key is optional.**
@@ -245,10 +259,10 @@
The layout you choose will determine the site's behaviour when navigating to the index for a chapter (which is resolved automatically when referencing a subdirectory's path without a trailing page path.) Choose the `chapter-index` layout if you would like the web browser to display a list of links to the pages in the chapter, or the `chapter-redirect` layout if you would like the web browser to automatically redirect to the first page in the chapter.
If you choose to provide a chapter description then this will be displayed on the chapter's index page when using the `chapter-index` layout, and will also be displayed under the chapter's name if you generate a list of chapters with the `chapter-list.html` include (which is designed to be used on the front page of a site.)
-If you use the `chapter-index` layout for a chapter and the global setting `theme-settings.indices` is set to `true` then a link will be generated for the chapter index in the site's navigation sidebar.
+If you use the `chapter-index` layout for a chapter and the global setting `theme-settings.navigation.indices` is set to `true` then a link will be generated for the chapter index in the site's navigation sidebar.
#### Content structure: site root
You can specify custom content for the site's front page by providing an `index.html` or `index.md` file in the root of your site's filesystem directory. The `chapter-list.html` include that ships with the theme is designed for use from the site root, and generates a list of chapters for you (with per-chapter descriptions included if they were specified.)