mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-09-13 05:13:33 -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
15
_includes/components/aux_nav.html
Normal file
15
_includes/components/aux_nav.html
Normal file
@@ -0,0 +1,15 @@
|
||||
<nav aria-label="Auxiliary" class="aux-nav">
|
||||
<ul class="aux-nav-list">
|
||||
{% for link in site.aux_links %}
|
||||
<li class="aux-nav-list-item">
|
||||
<a href="{{ link.last }}" class="site-button"
|
||||
{% if site.aux_links_new_tab %}
|
||||
target="_blank" rel="noopener noreferrer"
|
||||
{% endif %}
|
||||
>
|
||||
{{ link.first }}
|
||||
</a>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</nav>
|
||||
15
_includes/components/breadcrumbs.html
Normal file
15
_includes/components/breadcrumbs.html
Normal file
@@ -0,0 +1,15 @@
|
||||
{% unless page.url == "/" %}
|
||||
{% if page.parent %}
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.grand_parent %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
|
||||
{% else %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
|
||||
{% endif %}
|
||||
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
|
||||
</ol>
|
||||
</nav>
|
||||
{% endif %}
|
||||
{% endunless %}
|
||||
9
_includes/components/children_nav.html
Normal file
9
_includes/components/children_nav.html
Normal file
@@ -0,0 +1,9 @@
|
||||
<hr>
|
||||
{% include toc_heading_custom.html %}
|
||||
<ul>
|
||||
{% for child in include.toc_list %}
|
||||
<li>
|
||||
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
34
_includes/components/footer.html
Normal file
34
_includes/components/footer.html
Normal file
@@ -0,0 +1,34 @@
|
||||
{% capture footer_custom %}
|
||||
{%- include footer_custom.html -%}
|
||||
{% endcapture %}
|
||||
{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<hr>
|
||||
<footer>
|
||||
{% if site.back_to_top %}
|
||||
<p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
|
||||
{% endif %}
|
||||
|
||||
{{ footer_custom }}
|
||||
|
||||
{% if site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<div class="d-flex mt-2">
|
||||
{% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}
|
||||
<p class="text-small text-grey-dk-000 mb-0 mr-2">
|
||||
Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
|
||||
</p>
|
||||
{% endif %}
|
||||
{% if
|
||||
site.gh_edit_link and
|
||||
site.gh_edit_link_text and
|
||||
site.gh_edit_repository and
|
||||
site.gh_edit_branch and
|
||||
site.gh_edit_view_mode
|
||||
%}
|
||||
<p class="text-small text-grey-dk-000 mb-0">
|
||||
<a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}{% if page.collection and site.collections_dir %}/{{ site.collections_dir }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
|
||||
</p>
|
||||
{% endif %}
|
||||
</div>
|
||||
{% endif %}
|
||||
</footer>
|
||||
{% endif %}
|
||||
11
_includes/components/header.html
Normal file
11
_includes/components/header.html
Normal file
@@ -0,0 +1,11 @@
|
||||
<div id="main-header" class="main-header">
|
||||
{% if site.search_enabled != false %}
|
||||
{% include components/search_header.html %}
|
||||
{% else %}
|
||||
<div></div>
|
||||
{% endif %}
|
||||
{% include header_custom.html %}
|
||||
{% if site.aux_links %}
|
||||
{% include components/aux_nav.html %}
|
||||
{% endif %}
|
||||
</div>
|
||||
5
_includes/components/mermaid.html
Normal file
5
_includes/components/mermaid.html
Normal file
@@ -0,0 +1,5 @@
|
||||
<script>
|
||||
var config = {% include mermaid_config.js %};
|
||||
mermaid.initialize(config);
|
||||
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
|
||||
</script>
|
||||
7
_includes/components/search_footer.html
Normal file
7
_includes/components/search_footer.html
Normal file
@@ -0,0 +1,7 @@
|
||||
{% if site.search.button %}
|
||||
<a href="#" id="search-button" class="search-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
|
||||
</a>
|
||||
{% endif %}
|
||||
|
||||
<div class="search-overlay"></div>
|
||||
9
_includes/components/search_header.html
Normal file
9
_includes/components/search_header.html
Normal file
@@ -0,0 +1,9 @@
|
||||
{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
|
||||
|
||||
<div class="search">
|
||||
<div class="search-input-wrap">
|
||||
<input type="text" id="search-input" class="search-input" tabindex="0" placeholder="{{ search_placeholder | strip_html | strip }}" aria-label="{{ search_placeholder | strip_html| strip }}" autocomplete="off">
|
||||
<label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
|
||||
</div>
|
||||
<div id="search-results" class="search-results"></div>
|
||||
</div>
|
||||
69
_includes/components/sidebar.html
Normal file
69
_includes/components/sidebar.html
Normal file
@@ -0,0 +1,69 @@
|
||||
<div class="side-bar">
|
||||
<div class="site-header">
|
||||
<a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
|
||||
<a href="#" id="menu-button" class="site-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
|
||||
</a>
|
||||
</div>
|
||||
<nav aria-label="Main" id="site-nav" class="site-nav">
|
||||
{% assign pages_top_size = site.html_pages
|
||||
| where_exp:"item", "item.title != nil"
|
||||
| where_exp:"item", "item.parent == nil"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include nav.html pages=site.html_pages key=nil %}
|
||||
{% endif %}
|
||||
{%- if site.nav_external_links -%}
|
||||
<ul class="nav-list">
|
||||
{%- for node in site.nav_external_links -%}
|
||||
<li class="nav-list-item external">
|
||||
<a href="{{ node.url | absolute_url }}" class="nav-list-link external">
|
||||
{{ node.title }}
|
||||
{% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
|
||||
</a>
|
||||
</li>
|
||||
{%- endfor -%}
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 or pages_top_size > 0 %}
|
||||
{% if collection_value.nav_fold == true %}
|
||||
<ul class="nav-list nav-category-list">
|
||||
<li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
|
||||
{%- if collection.size > 0 -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
</li>
|
||||
</ul>
|
||||
{% else %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% else %}
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
|
||||
{% capture nav_footer_custom %}
|
||||
{%- include nav_footer_custom.html -%}
|
||||
{% endcapture %}
|
||||
{% if nav_footer_custom != "" %}
|
||||
{{ nav_footer_custom }}
|
||||
{% else %}
|
||||
<footer class="site-footer">
|
||||
This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
|
||||
</footer>
|
||||
{% endif %}
|
||||
</div>
|
||||
Reference in New Issue
Block a user