2495d3e6bb
Hi everyone, this is a large refactoring PR that looks to **modularize site components** following the discussion in #959. At the top-level, it: - moves icons, the sidebar, header (navbar, search, aux links), footer, and mermaid components of the `default` layout into their own `_includes` - creates a new `minimal` layout that does not render the header or sidebar as a proof-of-concept for the composability of components - documents all existing and new layouts (including vendor code) in the "Customization" section An important goal of this PR is for it to be **just code motion and flexibility**: there should be **zero impact** on the average end user that only consumes the `default` theme. The next few sections go in-depth on each of the listed changes. ### new components The `default` layout contains a "list" of all relevant components. Importantly, some of these components have sub-components: - the header is split into the search bar, custom code, and aux links - the icons include imports different icon components, some of which are conditionally imported by feature guards There are also candidates for future splits and joins: - the sidebar could be split into navigation, collections, external link, and header/footer code - the "search footer" could be joined with other search code, which would make it easier to "include search" in one go; *however, this is a markup change* - @kevinlin1 has pointed out that there is some leakage between the sidebar (which computes parents/grandparents) and the breadcrumbs (which needs them to render). He's graciously added a bandaid fix to `minimal` (which does not render the sidebar). However, in the long term, we should either: - calculate this in a parent and pass the information to both components - change how this works entirely (which may happen with multi-level navigation) @pdmosses has done a great job outlining this and more in his [Modular Layouts test site](https://pdmosses.github.io/modular-layouts/docs/main/). ### minimal layout Based on @kevinlin1's use-case in just-the-class (see: his [Winter 2023 CSE 373 site](https://courses.cs.washington.edu/courses/cse373/23wi/)), we've created a first-class `minimal` layout that does not render the sidebar or header. In a [comment](https://github.com/just-the-docs/just-the-docs/pull/1058#discussion_r1057015039), Kevin has indicated that we can re-add the search bar in the minimal layout; however, it seems like this would be a code change. I think we should punt this to a future issue/PR. @pdmosses has also discussed the confusion of `minimal` as a layout and its meaning in inheritance. I've added a note in documentation to clarify the (lack of) inheritance relationship. ### documentation I've written documentation in the "Customization" page / [Custom layouts and includes](https://deploy-preview-1058--just-the-docs.netlify.app/docs/customization/#custom-layouts-and-includes) section explaining: - generally, that we use includes/layouts (and pointing to docs) - the `default` layout and its constituent components (with a warning about name collisions) - creating alternative layouts with `minimal` as an example - the inheritance chain of layouts and the vendor layouts that we consume I've also created (and linked to) a [minimal layout test](https://deploy-preview-1058--just-the-docs.netlify.app/docs/minimal-test/) that is currently a copy of the markdown kitchen sink but with the minimal layout. I think there's room to improve this in the future. ### future work I think there's a lot we can do. Let me break this into various sections. Potential follow-ups before `v0.4.0`: - re-including search in `minimal` (anticipating a minor code change) - fixing the leakage of parent/grandparent information between the sidebar and breadcrumbs (anticipating no end-user code change, but good to evaluate separately and discuss) - heavily document this in the migration guide (#1059) and in our RC4 release docs - improve semantic markup for components (ex `main`, `nav`) Related work in later minor versions: - split up components into smaller components - allow users to easily customize new layouts using frontmatter (see @kevinlin1's [comment in #959](https://github.com/just-the-docs/just-the-docs/issues/959#issuecomment-1249755249)) Related work for `v1.0` (i.e. a major breaking change): - rename and better categorize existing includes - standardizing the "custom" includes - moving other components to the `components/` folder (ex `head`, `nav`) - potentially: less confusing naming for various components - potentially separate the search and header as components, so that they are completely independent Tangentially related work: - more flexible grid (see @JPrevost's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1363314610)) - a formal [feature model](https://en.wikipedia.org/wiki/Feature_model) of JTD, documenting feature dependence (see @pdmosses's [comment in this PR thread](https://github.com/just-the-docs/just-the-docs/pull/1058#issuecomment-1365414023)) - better annotate new features (motivated by writing these docs) - we should add "New" to new features :) - we should note when a feature was introduced (I think this is a core part of most software documentation) - we should annotate things that are "Advanced" in so far as the average Just the Docs user will not use them / they require significant Jekyll knowledge --- Closes #959.
Just the Docs
A modern, highly customizable, and responsive Jekyll theme for documentation with built-in search.
Easily hosted on GitHub Pages with few dependencies.
Installation
Use the template
The Just the Docs Template provides the simplest, quickest, and easiest way to create a new website that uses the Just the Docs theme. To get started with creating a site, just click "use the template"!
Note: To use the theme, you do not need to clone or fork the Just the Docs repo! You should do that only if you intend to browse the theme docs locally, contribute to the development of the theme, or develop a new theme based on Just the Docs.
You can easily set the site created by the template to be published on GitHub Pages – the template README file explains how to do that, along with other details.
If Jekyll is installed on your computer, you can also build and preview the created site locally. This lets you test changes before committing them, and avoids waiting for GitHub Pages.1 And you will be able to deploy your local build to a different platform than GitHub Pages.
More specifically, the created site:
- uses a gem-based approach, i.e. uses a
Gemfileand loads thejust-the-docsgem - uses the GitHub Pages / Actions workflow to build and publish the site on GitHub Pages
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
Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
Add this line to your Jekyll site's Gemfile:
gem "just-the-docs"
And add this line to your Jekyll site's _config.yml:
theme: just-the-docs
And then execute:
$ bundle
Or install it yourself as:
$ gem install just-the-docs
Alternatively, you can run it inside Docker while developing your site
$ docker-compose up
Usage
View the documentation for usage information.
Contributing
Bug reports, proposals of new features, and pull requests are welcome on GitHub at https://github.com/just-the-docs/just-the-docs. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
Submitting code changes:
- Submit an Issue that motivates the changes, using the appropriate template
- Discuss the proposed changes with other users and the maintainers
- Open a Pull Request
- Ensure all CI tests pass
- Provide instructions to check the effect of the changes
- Await code review
Design and development principles of this theme:
- As few dependencies as possible
- No build script needed
- First class mobile experience
- Make the content shine
Development
To set up your environment to develop this theme: fork this repo, the run bundle install from the root directory.
A modern devcontainer configuration for VSCode is included.
Your theme is set up just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
When this theme is released, only the files in _layouts, _includes, and _sass tracked with Git will be included in the gem.
License
The theme is available as open source under the terms of the MIT License.