This involves some explicit adding of gems that were moved out of the default gems:
- `base64` and `csv` are needed for both Jekyll 3.9 and Jekyll 4.3
- `bigdecimal` is just needed for Jekyll 3.9
In the ideal case, this gets backported to both Jekyll 3.9 and 4.3 so we don't need custom Gemfiles. But, I'm also okay with adding these manually for now, and then reverting once both get a backport that patches this. Reminds me of webrick!
It doesn't seem like any of our theme developers use this (out of date) `Dockerfile`, and we're probably better served placing more of this in the theme template (so users can consume it). I think this is part of our overall movement to not have users of our theme directly clone this repo.
Fix#1587
As reported in issue #1587, the auto-generated child navigation (TOC) has a bug: it can be incorrectly omitted. This happens when the first page built is a parent page. The omission is caused by a side-effect of including the cached site-nav HTML: the code that generates the site-nav is executed the first time the cached HTML is included, and assignments in the executed code may overwrite the values of variables.
@kevinlin1 suggested a simple and safe way to fix this bug: move the inclusion of the site-nav in `components/children_nav.html` so that it is executed before all local assignments. This PR implements that suggestion, and applies the same fix to two other files.
### Testing
A test for this bug has been added to the [_Just the Docs Tests_ repo](https://github.com/just-the-docs/just-the-docs-tests). The first page rendered when building the website is `About this site` in the TESTS collection, and it is now the `parent` of the page [`Test TOC`](https://just-the-docs.github.io/just-the-docs-tests/tests/about/test-toc/), which should be listed in its auto-generated child navigation. (The test page uses `nav_exclude: true` to avoid the link to it appearing in the main navigation, but that doesn't affect the test of this PR.)
The following steps check that the bug appears when building _Just the Docs Tests_ with v0.10.0 of the theme:
1. Clone the [Just the Docs Tests repo](https://github.com/just-the-docs/just-the-docs-tests).
2. Build and serve the website locally using:
```sh
JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle install
JTD_ORG=just-the-docs JTD_REF=v0.10.0 bundle exec jekyll serve
```
3. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
4. Check that no auto-generated child navigation appears on the latter page.
The following steps check that the bug does not appear when building _Just the Docs Tests_ with this PR branch:
5. Build and serve the website locally using:
```sh
JTD_ORG=pdmosses JTD_REF=fix-toc bundle install
JTD_ORG=pdmosses JTD_REF=fix-toc bundle exec jekyll serve
```
6. Check that the `Test TOC` page at `.../just-the-docs-tests/tests/about/test-toc/` is a child of the `About this site` page at `.../just-the-docs-tests/tests/about/`.
7. Check that an auto-generated child navigation with a link to the `Test TOC` page appears on the latter page.
(It seems unnecessary to check that the reported bug does not appear on other pages, since subsequent includes of the cached site-nav cannot assign to any variables.)
This is the minimum necessary change to make `back_to_top` work when there is no custom footer, last edit timestamp, or GitHub edit link.
Two immediate thoughts. First, we have a pair of variables: `back_to_top` and `back_to_top_text`. In my opinion, this seems a bit unnecessary; we could just use a `back_to_top`, and treat any non-`nil`/`false` value as the text. We could make this backwards compatible (i.e. support but deprecate `back_to_top_text`). Any thoughts here?
Secondly, some of these conditions are weak:
a251382b7a/_includes/components/footer.html (L7-L9)
Here, this conditional *should* also check for `back_to_top_text`, and presumably, this should "bubble up" to the overall `if` statement on line 4 (similar things for the `gh_*` variables - the line 4 condition only checks for `gh_edit_link`). Is this a reasonable concern/take? If so, I can approach this some time (either in this PR, in another PR, etc.).
---
After we decide the correct behaviour of `back_to_top`, I'll add documentation to the "Configuration" section!
Separately, @pdmosses mentioned:
> The obvious fix is to always render the footer when `site.back_to_top` is set. However, it would improve the usability of the back-to-top feature if individual pages could override the site setting (to suppress the link on some short pages, or to show it on some long pages).
Happy to do that too - for organizational purposes, I'll punt that to another PR (that I can merge into the same release).
---
Fixes#1443.
@@ -32,7 +32,7 @@ More specifically, the created site:
Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
### Use RubyGems
### Use as a RubyGem
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
@@ -48,17 +48,11 @@ And add this line to your Jekyll site's `_config.yml`:
theme:just-the-docs
```
And then execute:
And then install all relevant dependencies:
$ bundle
Or install it yourself as:
$ gem install just-the-docs
Alternatively, you can run it inside Docker while developing your site
@@ -19,6 +19,27 @@ To support in-page navigation, you can generate a *Table of Contents* (TOC) with
To generate a *Table of Contents* in a page, you use Kramdown's `{:toc}` method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels.
{: .note }
`{:toc}` can be used only once on each page.
You **must** have a list immediately preceding the table of contents. The type of list determines the style of your table of contents.
For an *ordered* table of contents, use the following markdown code:
```md
1. TOC
{:toc}
```
The `{:toc}` line *must* follow the `1. TOC` line, which begins a list.
For an *unordered* table of contents, instead use the following markdown code:
```
- TOC
{:toc}
```
## Omitting Heading from Table of Contents
If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names).
@@ -36,8 +57,6 @@ If you want to omit a particular heading from the TOC, follow it immediately by
This example omits the top-level heading (`In-Page Navigation`) from the TOC, as well as the heading for the *Table of Contents* itself.
To get an unordered list, replace `1. TOC` by `- TOC` in the above example.
## Collapsible Table of Contents (with `<details>` and `<summary>`)
You can make the Table of Contents collapsible using the `<details>` and `<summary>` elements, as in the following example.
@@ -55,9 +74,6 @@ You can make the Table of Contents collapsible using the `<details>` and `<summa
The attribute `open` (which expands the Table of Contents by default) and the styling (here with `text-delta`) are optional.
The main navigation for your Just the Docs site is at the left side of the page on large screens, and at the top (behind a tap) on small screens.
The main navigation for your Just the Docs site is at the left side of the page on large screens, and at the top (behind a tap) on small screens.
You need to specify the `title` of each page in its front matter. Page titles are independent of file names and directory structure. The navigation uses the title of the page as an anchor for links to the page.
By default, links to all pages appear in the main navigation at the top level, ordered alphabetically by their titles. By adding further fields to the front matter of individual pages, you can [change their order]({% link docs/navigation/main/order.md %}), [exclude pages]({% link docs/navigation/main/exclude.md %}), and change their [parent pages]({% link docs/navigation/main/levels.md %}).
{: .new-title }
> New (Multi-level)
> New (v0.10.0)
>
> The main navigation can be structured as a multi-level menu of unlimited depth:
> pages can always have child pages.
@@ -25,16 +25,16 @@ For the construction of the navigation display to work (and to avoid potential c
* The title of each page must be different from the titles of all its child pages, and from the titles of their child pages, etc.
{: .new-title }
> New (Multi-level)
> New (v0.10.0)
>
> If *all* the pages of your site have different titles, you need only to specify the `title` of each page, and the `parent` title of each lower-level page.[^1]
[^1]: Previous versions of Just the Docs restricted the navigation to three levels. You also needed to specify `has_children: true` on all parent pages, and a `grand_parent` title on all grandchild pages. The `has_children` parameter is now redundant, and the `grand_parent` parameter can usually be omitted.
If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter.
If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter.
{: .new-title }
> New (Multi-level)
> New (v0.10.0)
>
> For deeper navigation structures, you can specify the title of a grandparent or higher level page as an `ancestor` title.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
