Pages and collections #448
Conversation
- Move `docs/tests` pages to `_tests` collection. - Create `_tests_config.yml` to include tests. - Update `_cnfig.yml` instructions for including tests. - Update links in `_tests/navigation/index.md`. - Update `_layout/default.html` to output site.html_pages and/or collections. - Test by running `bundle exec jekyll serve --config _tests_config.yml`.
- Discount excluded pages
- Update the section on configuration of collections to include normal pages.
- Avoid irrelevant conflicts when updating from master
- Remove duplicated configuration code from `_tests_config.yml` - Rename to `_tests.yml` The tests collection is ignored when not mentioned, so it does not need to be excluded in `_config.yml`.
|
@pmarsceill I've removed the conflicts and updated to v0.3.3. To include the tests locally: The new config |
- Fix a bug with the breadcrumbs list, where a link on a grandchild page can point to the wrong parent page, following the solution suggested by @AdityaTiwari2102 in just-the-docs#477
The TOC/breadcrumb links in "Tests" and "Test Collection 1" exhibit the bug reported in just-the-docs#492. To fix the bug, this PR needs merging with just-the-docs#494.
|
Just posting to show interest in this PR being reviewed. I have been using the |
|
@clberube Many thanks for the feedback regarding this PR – it's good to know that someone is successfully using the updated default layout. I hope the proposed changes will soon be reviewed, and included in the next release. |
Serve locally: ``` bundle exec jekyll serve --config _config.yml,_config_dev.yml ``` Test locally: ``` bundle exec jekyll serve --config _config.yml,_config_dev.yml,_tests.yml ```
- Fix a bug that affects sites with no child pages
- Relax version constraints in response to failing check `Could not find gem 'bundler (~> 2.1.4)' in any of the relevant sources`
- Cover all combinations of `search_exclude` and `nav_exclude` in `_tests.yml` Searching for C2 and C4 should return results, C1 and C5 not. Navigation for pages, C1, C2, C3 should appear, C4 and C5 not.
|
Just another request for this functionality to be reviewed/merged. The ability to show both pages and collections in the nav is vital for our site. |
|
@jthrilly if you add a copy of https://github.com/pdmosses/just-the-docs/blob/pages-and-collections/_layouts/default.html to the sources for your site, jekyll will use it instead of the layout from the current release. This lets you use the pages-and-collections feature on your site straight away, independently of the next release of the theme. However, please bear in mind that this PR has not yet been reviewed, and the reviewer might suggest changes. When the next version of the theme is released, the default layout is likely to change, and you should then remove or update your copy of the above file before rebuilding your site (unless you pin the theme to |
|
Thanks for the tip @pdmosses - unfortunately, I've just spent a fair amount of time refactoring to remove some previous customisations to this template for our site, which broke when updating the theme! Keen to stick with released versions for maintainability. |
|
@jthrilly It is possible to use this feature before the next release without copying any theme files. Change the remote theme setting in remote_theme: pdmosses/just-the-docs@pages-and-collectionsChange the gem "just-the-docs", github: "pdmosses/just-the-docs", branch: "pages-and-collections"Then your site should build as if this feature has already been merged. |
Manually merge the relevant changes from PR just-the-docs#494, namely: When configured for more than one collection, v0.3.2 produces empty TOCs of children in all but the last collection, due to referencing the overwritten `pages_list` in `_layouts/default.html`. When the same parent title is used in different collections, v0.3.2 can also produce a link to the wrong collection. Moreover, v0.3.3 can also produce incorrect breadcrumb links; see issue just-the-docs#492. - Move the breadcrumbs link variable assignments from `_layouts/default.html` to `_includes/nav.html`, and make it conditional on `page` being in the current collection. - Correct the condition for assignment to `second_level_url`, as in just-the-docs#477. - Change the variable used for the TOC from `children_list` to `toc_list`, move its assignment from `_layouts/default.html` to `_includes/nav.html`, and make it conditional on `page` being in the current collection.
|
@pmarsceill this PR now incorporates the changes proposed in #494 and #477. (I merged the changes manually, to avoid having to resolve conflicts...) |
Amazing work, this is just what I'm looking for! I tried it (along with your |
For what it's worth I didn't have to edit the Gemfile at all to use branches as a remote themes. remote_theme: pdmosses/just-the-docs@collections-navin And make sure to comment out any lines that previously included a local theme: # theme: "just-the-docs" |
|
@clberube thanks for your input. @melat0nin the demo site at https://pdmosses.github.io/test-multi-level/ was built quite recently, based on a slightly earlier commit to If you want to add collections, they need to be specified as explained in the docs.
|
Thanks, I cloned your repo and got it working that way. It's exactly what I want, thanks for all your work on this :) How would you suggest using this in production now, in advance of it being integrated upstream (if it ever is)? Or should I just take a local copy of the theme, so if you delete your temporary branch I can continue to use it in future? |
Perhaps you could clone my If that works, you might then be able to pull any changes that I make, as well as having your own copy for when I delete my branch. Note that the branch used for PR #572 allows individual collections to be folded, as illustrated at https://pdmosses.github.io/just-the-docs/ but otherwise it should be the same as the one in this PR. Let's hope these PRs get reviewed before too long... For my own sites, I need multi-level navigation hierarchies (together with the features from all my other PRs) so I'm simply using my |
This PR combines (and resolves conflicts between) #448, #463, #466, #494, #495, #496, #498, and #572. The main aim is to facilitate use of several of the implemented features _together_, when using the fork as a remote theme. It should also simplify merging the included PRs into a future release. The branch [combination-rec-nav](https://github.com/pdmosses/just-the-docs/tree/combination-rec-nav) adds [multi-level navigation](#462) and (NEW:) [sibling links](#394) to the branch used for this PR. It includes updated [documentation for the navigation structure](https://pdmosses.github.io/just-the-docs/docs/navigation-structure/), and reorganised and extended [navigation tests](https://pdmosses.github.io/just-the-docs/tests/navigation/). The documentation and the tests can be browsed at the (temporary) [website published from the combination-rec-nav branch](https://pdmosses.github.io/just-the-docs/). _Caveat:_ The changes to v0.3.3 in this PR and #462 have not yet been reviewed or approved, and may need updating before merging into a release of the theme. If you use a branch from a PR as a remote theme, there is a risk of such updates affecting your website. Moreover, these branches are likely to be deleted after they have been merged. To avoid such problems, you could copy the branch that you want to use to your own fork of the theme. Co-authored-by: Matt Wang <[email protected]>
6 participants
See #447 for the proposal of the enhancement implemented by this PR.
docs/testspages to_testscollection._tests_config.ymlto include tests._config.ymlinstructions for including tests._tests/navigation/index.md._layout/default.htmlto output pages and/or collections.bundle exec jekyll serve --config _tests_config.yml.