Features that extend the excellent "Just the docs" Jekyll theme
Currently this project has implemented these features:
_config.yml
These features have been built for and are used with GitHub Pages.
Other Jekyll use-cases have not been tested and may contain bugs or not work at all.
The recommended way to install this project is by installing it as a remote
theme. In your project's _config.yml
add:
remote_theme: Potherca/extend-the-docs@theme
After it has been installed and configured, the theme should "just work".
To use a feature, it must be enabled in the _config.yml
file under the nav
section.
To have the top-level of the navigation menu be all repositories of a user (or
organisation) the nav.cross_repository
value can be set in the _config.yml
:
nav:
cross_repository: true
All links point to the GitHub Pages URL of each repository or, if no GitHub Pages are available, to the homepage set for the repository. If neither is available, no link is shown.
To always use the repository homepage, set nav.cross_repository.show_homepage
to true
.
nav:
cross_repository:
show_homepage: true
Any repositories that should be excluded can be set in nav.cross_repository.exclude
.
nav:
cross_repository:
exclude:
- example.github.io
By default, archived repositories are also shown in the navigation menu. They
can be hidden by setting nav.cross_repository.show_archived
to false
.
nav:
cross_repository:
show_archived: false
nav:
cross_repository:
# Any repository mentioned here will not be included in the navigation menu
exclude:
- potherca.github.io
# Set to true to also include repositories that have been archived
show_archived: false
# Set to true to use the homepage (from the repository settings) instead of https://site.url/repository-name
show_homepage: true
A custom path to the favicon can be set in the _config.yml
using:
nav:
favicon_ico: /favicon.ico
Please note that this path is used as-is (i.e. it is not a relative path within the repo).
_config.yml
To exclude pages, they can be added to nav.exclude
, instead of adding
frontmatter:
nav:
exclude:
# The URL of any page that should not be displayed in the navigation menu
- "/404.html"
By default, pages are not added to the menu structure. To include posts, set
nav.include_posts
to true
:
nav:
include_posts: true
By default, posts will be sorted by their title, not by publishing date.
To sort by date instead of title:
nav:
include_posts:
sort_by_date: true
The link or text displayed for the main link can be changed:
nav:
main_title:
link: '/'
text: Alternative Title
This can be useful to link to a generic homepage rather than repository home.
The navigation menu can follow the structure of documents in a repository for the parent/child structure, instead of using the frontmatter.
To do this, set nav.recurse
to true
:
nav:
recurse: true
nav:
cross_repository:
exclude:
- example.github.io
show_archived: false
show_homepage: true
exclude:
- "/404.html"
favicon_ico: /favicon.ico
include_posts:
sort_by_date: true
main_title:
link: '/'
text: Alternative Title
recurse: true
Questions or feedback can be given by opening an issue on GitHub.
Like all Potherca's projects, this project adheres to the Contributor Covenant Code of Conduct
This project has been published by Potherca under a Mozilla Public License 2.0 (MPL-2.0).