mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-09-16 06:13:32 -06:00
refactor: modularize site components (#1058)
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.
This commit is contained in:
Matt Wang
GitHub
@@ -212,3 +212,158 @@ Chercher notre site
|
||||
{% endraw %}
|
||||
|
||||
would make the placeholder text "Chercher notre site". [Liquid code](https://jekyllrb.com/docs/liquid/) (including [Jekyll variables](https://jekyllrb.com/docs/variables/)) is also supported.
|
||||
|
||||
## Custom layouts and includes
|
||||
{: .d-inline-block }
|
||||
|
||||
New (v0.4.0)
|
||||
{: .label .label-green }
|
||||
|
||||
Advanced
|
||||
{: .label .label-yellow }
|
||||
|
||||
Just the Docs uses Jekyll's powerful [layouts](https://jekyllrb.com/docs/layouts/) and [includes](https://jekyllrb.com/docs/includes/) features to generate and compose various elements of the site. Jekyll users and developers can extend or replace existing layouts and includes to customize the entire site layout.
|
||||
|
||||
### Default layout and includable components
|
||||
|
||||
The `default` layout is inherited by most of the "out-of-the-box" pages provided by Just the Docs. It composes various re-usable components of the site, including the sidebar, navbar, footer, breadcrumbs, and various imports. Most users who create new pages or layouts will inherit from `default`.
|
||||
|
||||
Here is a simplified code example of what it looks like:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```liquid
|
||||
<!-- a simplified version of _layouts/default.html -->
|
||||
<html>
|
||||
{% include head.html %}
|
||||
<body>
|
||||
{% include icons/icons.html %}
|
||||
{% include components/sidebar.html %}
|
||||
{% include components/header.html %}
|
||||
{% 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.search_enabled != false %}
|
||||
{% include components/search_footer.html %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.mermaid %}
|
||||
{% include components/mermaid.html %}
|
||||
{% endif %}
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
#### Component summary
|
||||
{: .no_toc }
|
||||
|
||||
{: .warning }
|
||||
Defining a new `_includes` with the same name as any of these components will significantly change the existing layout. Please proceed with caution when adjusting them.
|
||||
|
||||
To briefly summarize each component:
|
||||
|
||||
- `_includes/head.html` is the entire `<head>` tag for the site; this imports stylesheets, various JavaScript files (ex: analytics, mermaid, search, and Just the Docs code), and SEO / meta information.
|
||||
- `_includes/icons/icons.html` imports all SVG icons that are used throughout the site. Some, such as those relating to search or code snippet copying, are only loaded when those features are enabled.
|
||||
- `_includes/components/sidebar.html` renders the sidebar, containing the site header, navigation links, external links, collections, and nav footer.
|
||||
- `_includes/components/header.html` renders the navigation header, containing the search bar, custom header, and aux links
|
||||
- `_includes/components/breadcrumbs.html` renders the breadcrumbs feature
|
||||
- `vendor/anchor_headings.html` is a local copy of Vladimir Jimenez's [jekyll-anchor-headings](https://github.com/allejo/jekyll-anchor-headings) snippet
|
||||
- `_includes/components/children_nav.html` renders a list of nav links to child pages on parent pages
|
||||
- `_includes/components/footer.html` renders the bottom-of-page footer
|
||||
- `_includes/components/search_footer.html` renders DOM elements that are necessary for the search bar to work
|
||||
- `_includes/components/mermaid.html` initializes mermaid if the feature is enabled
|
||||
|
||||
Each of these components can be overridden individually using the same process described in the [Override includes](#override-includes) section. In particular, the granularity of components should allow users to replace certain components (such as the sidebar) without having to adjust the rest of the code.
|
||||
|
||||
Future versions may subdivide components further; we guarantee that we will only place them in folders (ex `components/`, `icons/`, or a new `js/`) to avoid top-level namespace collisions.
|
||||
|
||||
### 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.
|
||||
|
||||
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:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
---
|
||||
layout: minimal
|
||||
title: Minimal layout test
|
||||
---
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Similarly, users and developers can create other alternative layouts using Just the Docs' reusable includable components.
|
||||
|
||||
### Default layout and inheritance chain
|
||||
|
||||
Under the hood,
|
||||
|
||||
- `default` and `minimal` 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.
|
||||
|
||||
### Overridden default Jekyll layouts
|
||||
|
||||
By default, Jekyll (and its default theme `minima`) provide the `about`, `home`, `page`, and `post` layouts. In Just the Docs, we override all of these layouts with the `default` layout. Each of those layouts is simply:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
---
|
||||
layout: default
|
||||
---
|
||||
|
||||
{{ content }}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Reference in New Issue
Block a user