Skip to content
Snippets Groups Projects
  • Matt Wang's avatar
    2495d3e6
    refactor: modularize site components (#1058) · 2495d3e6
    Matt Wang authored
    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.
    2495d3e6
    History
    refactor: modularize site components (#1058)
    Matt Wang authored
    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.