steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-12 21:03:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add nav_enabled variables for more customizable and feature-complete minimal layouts (#1441)

Browse Source 
* Add nav_enabled variables for site/layout/page-level control

* _sass: Add a space around `+` operator

* assets: Do not compile based on site.nav_enabled

* _config.yml: nav_enabled can be selectively enabled

* CHANGELOG.md: Add nav_enabled feature and docs

* docs: Prefer em dash in describing minimal layout

* docs: Add section on Selectively hiding or showing the sidebar

* _layouts: Display sidebar based on variable importance

* docs: Update documentation on the minimal layout

* docs: Document site.nav_enabled configuration variable

---------

Co-authored-by: Matt Wang <matt@matthewwang.me>
This commit is contained in:
Kevin Lin
2024-04-22 15:07:29 -07:00
committed by GitHub
parent 063a130ffd
commit a251382b7a
9 changed files with 85 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/configuration.md
View File

@@ -101,6 +101,14 @@ aux_links:
aux_links_new_tab: false
```
## Navigation sidebar
```yaml
# Enable or disable the side/mobile menu globally
# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout
nav_enabled: true
```
## Heading anchor links
```yaml

42
docs/customization.md
View File

@@ -329,43 +329,9 @@ Future versions may subdivide components further; we guarantee that we will only
### Alternative layouts and example (`minimal`)
Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, inspired by Kevin Lin's work in [just-the-class](https://github.com/kevinlin1/just-the-class). This `minimal` layout does not render the sidebar, header, or search. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, which disables the navigation sidebar. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
Here is a simplified code example of what it looks like:
{% raw %}
```liquid
<!-- a simplified version of _layouts/minimal.html -->
<html>
{% include head.html %}
<body>
{% include icons/icons.html %}
{% comment %} Bandaid fix for breadcrumbs here! {% endcomment %}
{% include components/breadcrumbs.html %}
{% if site.heading_anchors != false %}
{% include vendor/anchor_headings.html html=content ... %}
{% else %}
{{ content }}
{% endif %}
{% if page.has_children == true and page.has_toc != false %}
{% include components/children_nav.html %}
{% endif %}
{% include components/footer.html %}
{% if site.mermaid %}
{% include components/mermaid.html %}
{% endif %}
</body>
</html>
```
{% endraw %}
This layout is packaged in Just the Docs. Users can indicate this alternative layout in page front matter:
Users can indicate this alternative layout in page front matter:
{% raw %}
@@ -384,10 +350,10 @@ Similarly, users and developers can create other alternative layouts using Just
Under the hood,
- `default` and `minimal` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
- `default` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
- `table_wrappers` inherits from `vendor/compress`, which is a local copy of Anatol Broder's [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) Jekyll plugin
Note that as of now, `minimal` and `default` have no inheritance relationship.
The `minimal` layout inherits from the `default` but assigns `nav_enabled: false` to disable the navigation sidebar.
### Overridden default Jekyll layouts

15
docs/layout/layout.md
View File

@@ -28,7 +28,20 @@ Each page that has child pages generally has a list of links to those pages (you
## The `minimal` layout
A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar -- and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar---and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents.
## Selectively hiding or showing the sidebar
[Jekyll's front matter defaults] can be used to apply the `minimal` layout for many pages. But there are also other variables that can control the page layout. In `_config.yml`, you can set `nav_enabled: false` to disable the sidebar navigation panel across the entire site. This can then be selectively enabled on a page-by-page basis by assigning the `nav_enabled: true` page [front matter] variable. For instance, this could be used to enable sidebar navigation on a home page while all other pages have sidebar navigation disabled.
```yaml
---
layout: default
title: Home
nav_enabled: true
---
```
## Other layouts