steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-04 03:01:23 -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
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 85 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGELOG.md
View File

@ -17,11 +17,11 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
Code changes to `main` that are *not* in the latest release:
- N/A
- Added: `nav_enabled` site, layout, and page-level variable to selectively show or hide the side/mobile menu by [@kevinlin1] in [#1441]. The minimal layout was reimplemented using this feature, and now has support for the site-wide search bar and auxiliary links.
Docs changes made since the latest release:
- N/A
- Docs: Explained the `nav_enabled` variables as an alternative to using the minimal layout [@kevinlin1] in [#1441].
## Release v0.8.2

6
_config.yml
View File

@ -109,6 +109,10 @@ aux_links:
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
# 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
# Sort order for navigation links
# nav_sort: case_insensitive # default, equivalent to nil
nav_sort: case_sensitive # Capital letters sorted before lowercase
@ -121,7 +125,7 @@ nav_external_links:
liquid:
error_mode: strict
strict_filters: true
# Footer content
# appears at the bottom of every page's main content

8
_layouts/default.html
View File

@ -9,7 +9,13 @@ layout: table_wrappers
<body>
<a class="skip-to-main" href="#main-content">Skip to main content</a>
{% include icons/icons.html %}
{% include components/sidebar.html %}
{% if page.nav_enabled == true %}
{% include components/sidebar.html %}
{% elsif layout.nav_enabled == true and page.nav_enabled == nil %}
{% include components/sidebar.html %}
{% elsif site.nav_enabled != false and layout.nav_enabled == nil and page.nav_enabled == nil %}
{% include components/sidebar.html %}
{% endif %}
<div class="main" id="top">
{% include components/header.html %}
<div class="main-content-wrap">

34
_layouts/minimal.html
View File

@ -1,34 +1,6 @@
---
layout: table_wrappers
layout: default
nav_enabled: false
---
<!DOCTYPE html>
<html lang="{{ site.lang | default: 'en-US' }}">
{% include head.html %}
<body>
<a class="skip-to-main" href="#main-content">Skip to main content</a>
{% include icons/icons.html %}
<div class="main-content-wrap" id="top">
{% include components/breadcrumbs.html %}
<div id="main-content" class="main-content" role="main">
{% if site.heading_anchors != false %}
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
{% else %}
{{ content }}
{% endif %}
{% if page.has_children == true and page.has_toc != false %}
{% include components/children_nav.html %}
{% endif %}
{% include components/footer.html %}
</div>
</div>
{% if site.mermaid %}
{% include components/mermaid.html %}
{% endif %}
</body>
</html>
{{ content }}

60
_sass/layout.scss
View File

@ -19,23 +19,48 @@
width: calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width});
min-width: $nav-width;
}
& + .main {
@include mq(md) {
margin-left: $nav-width-md;
}
@include mq(lg) {
// stylelint-disable function-name-case
// disable for Max(), we want to use the CSS max() function
margin-left: Max(
#{$nav-width},
calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
);
// stylelint-enable function-name-case
}
.main-header {
display: none;
background-color: $sidebar-color;
@include mq(md) {
display: flex;
background-color: $body-background-color;
}
&.nav-open {
display: block;
@include mq(md) {
display: flex;
}
}
}
}
}
.main {
margin: auto;
@include mq(md) {
position: relative;
max-width: $content-width;
margin-left: $nav-width-md;
}
@include mq(lg) {
// stylelint-disable function-name-case
// disable for Max(), we want to use the CSS max() function
margin-left: Max(
#{$nav-width},
calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
);
// stylelint-enable function-name-case
}
}
@ -53,23 +78,12 @@
.main-header {
z-index: 0;
display: none;
background-color: $sidebar-color;
border-bottom: $border $border-color;
@include mq(md) {
display: flex;
justify-content: space-between;
height: $header-height;
background-color: $body-background-color;
border-bottom: $border $border-color;
}
&.nav-open {
display: block;
@include mq(md) {
display: flex;
}
}
}

8
assets/js/just-the-docs.js
View File

@ -556,12 +556,14 @@ function activateNav() {
// Document ready
jtd.onReady(function(){
initNav();
if (document.getElementById('site-nav')) {
initNav();
activateNav();
scrollNav();
}
{%- if site.search_enabled != false %}
initSearch();
{%- endif %}
activateNav();
scrollNav();
});
// Copy button on code

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