Layout Options

[DavieReid]

The Frame

The frame can be thought of the components that side around the main page content. The furniture so to speak. For Mosaic this includes:

• Header
• Footer
• Left Sidebar (a vertical navigation) - navigate to any page
• Right Sidebar (table of contents) - navigate within pages
• Breadcrumbs - show where you are and allow quick navigation to a previous page
• Doc Paginator - navigate to next/prev page

How to set a Page Layout

It is set in the frontmatter of a page using the layout field. If no layout is provided then the FullWidth layout is used by default.

Existing Layouts

The table below details he existing layouts and what frame components they use.

Layout Name	Header	Footer	Sidebar	TOC	Breadcrumbs	Doc Paginator	Full Width Content (max width is 1440px)
DetailContentOnly	✅	✅	🚫	🚫	✅	🚫	✅
DetailHighlight	✅	✅	🚫	✅	✅	🚫	🚫
DetailOverview	✅	✅	✅	🚫	✅	✅	🚫
DetailTechnical	✅	✅	✅	✅	✅	✅	🚫
Edit	✅	🚫	🚫	🚫	🚫	🚫	✅
FullWidth	✅	🚫	🚫	🚫	🚫	🚫	✅
Landing	✅	✅	🚫	🚫	🚫	🚫	✅
Newsletter	✅	✅	✅	🚫	🚫	✅	🚫
ProductDiscover	✅	✅	🚫	🚫	✅	🚫	✅
ProductPreview	✅	✅	🚫	🚫	🚫	🚫	✅

Observations

1. Every layout has a header.
2. If a layout does not have a sidebar or a TOC then it is full width. The only exception is theDetailContentOnly layout.
3. Edit/FulllWidth/Landing are very similar.
4. ProductDiscover and DetailContentOnly are identical.
5. ProductPreview and Landing are identical.
6. The names of the layouts are not clearly describing what frame components will be used by the page.

Future Design

1. Built in Header

Build in the Header component into the Base Layout. It is always needed and I can't see a design that wouldn't have the header in it. This simplifies the logic for all layouts.

2. Frame frontmatter

Instead of stating the name of the layout in the frontmatter, you can choose to enable/disable frame components. This gives users flexibility to show/hide the frame components at will.

---
title: A Title
description: A description
frame:
   footer: true
   sidebar: true
   toc: true
   breadcrumbs: true
   paginator: true
---

If you choose to have sidebar:false and toc:false then the page content is full width.
There is no option to disable a header.

Benefits

• Maximum flexibility.
• Less terminology to learn. Don't need to know the difference between for example a ProductDiscover and ProductPreview layout.
• I think/hope this will result in a simpler implementation. A layout becomes a component that reads the config from the frontmatter and acts accordingly. This will improve extensibility when teams potentially add their own layouts.
• Reduces redundancy.

Downsides

• Even if it's not clear what the layouts do it is very easy to set the layout and change it in the frontmatter if needed.
• We would need to find a way to migrate from the existing system to the new system.

[JoanaMMoreira]

It would also be useful to have the option of having a full width footer for doc layouts.

[JoanaMMoreira]

On the Salt site we also extracted the page title so we could apply some custom styling so maybe this is something that would be useful to document e.g.

 const {
    meta: { title },
  } = useMeta();

<h1 className={layoutStyles.title}>{title}</h1>

[mark-tate]

Pros

• it's simpler, the names for layouts always end up tied to a use-case, rather than being generic

Cons

• A layout is a standard thing but being able to turn things on and off, might create inconsistency
  Do we have to specify these same values on every page to maintain consistency?

Questions

• With the Typescript plugin, it needed it's own layout and it's own sidebar ?
  How would we support anatomy variants ?
• How does this fit into the NextJs Layouts which we want to refactor to ?
• The props for the anatomy parts are separate from the enabled/disabled flag, is that confusing
  Someone could specify props but forget to add the enable/disable flag
• Would the Salt layout components, add any value to the implementation? It feels like this use-case is the reason they were created
• Should a page author need to know about Layout anatomy's they just need to provide content

[honey-chang]

• I like the turning on and off frame, as our layout namings are not clear but I also have concern about the consistency. We can provide guideline for the layouts, giving standard for frame setting.

• Can we make footer in fullwidth?
  
  something like this..

This is the design mockup that we discussed new footer design in the past.

• We need to think about Hero component usage. Currently it's matching with Layouts. (Ex. Fullwidth variant only for Landing layout, Product discover etc..) Once layouts are updated, hero component usage should be changed.

[DavieReid]

On the Salt site we also extracted the page title so we could apply some custom styling so maybe this is something that would be useful to document e.g.

 const {
    meta: { title },
  } = useMeta();

<h1 className={layoutStyles.title}>{title}</h1>

In a page you can reference meta data with curly brackets so this should work (and will be documented)

 <h1 className={meta.title}>{title}</h1>

[DavieReid]

• I like the turning on and off frame, as our layout namings are not clear but I also have concern about the consistency. We can provide guideline for the layouts, giving standard for frame setting.
• Can we make footer in fullwidth?
  
  something like this..

This is the design mockup that we discussed new footer design in the past.

• We need to think about Hero component usage. Currently it's matching with Layouts. (Ex. Fullwidth variant only for Landing layout, Product discover etc..) Once layouts are updated, hero component usage should be changed.

I think we need to choose a very sensible default and/or build this into page templates that people can copy. So these layouts that we currently have become templates rather than layouts potentially.

We can make the footer full width without making additional changes so i will create an issue for that.