Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix heading padding FOUC (option 3 with modifications: sticky header) #1939

Merged
merged 24 commits into from
Jun 16, 2022
Merged

Fix heading padding FOUC (option 3 with modifications: sticky header) #1939

Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
28c3358
Both options
ang-zeyu May 13, 2022
2ed7491
Make sticky demo non-searchable
ang-zeyu May 25, 2022
c3fa410
update tests
ang-zeyu May 25, 2022
597019b
typo
ang-zeyu May 25, 2022
12979af
Finish mobile <header sticky>'s site / page nav
ang-zeyu May 25, 2022
a91e90a
Cleanup, fix / streamline resizing logic
ang-zeyu Jun 10, 2022
0b44177
Ug edits
ang-zeyu Jun 10, 2022
e24c96e
Sticky header only
ang-zeyu Jun 10, 2022
39a6eaa
Test file updates
ang-zeyu Jun 10, 2022
98485a5
remove 1 more [fixed] selector
ang-zeyu Jun 10, 2022
8a4cae8
some more test file updates
ang-zeyu Jun 10, 2022
5eb413f
Merge branch 'master' into fix-fixed-header-both
ang-zeyu Jun 10, 2022
526f273
padding tweak
ang-zeyu Jun 10, 2022
41af9f5
Remove some unnecessary padding changes from header[fixed]
ang-zeyu Jun 10, 2022
3728ec3
Add another example
ang-zeyu Jun 10, 2022
38d5a9e
link "css variable" to mdn docs
ang-zeyu Jun 10, 2022
b5672db
Update scrolling logic
ang-zeyu Jun 10, 2022
fd74b17
overflow-x for content wrapper
ang-zeyu Jun 11, 2022
a58bb21
Adapt scrolling properly
ang-zeyu Jun 11, 2022
e9f6732
overflow-x for content wrapper (other files+update tests)
ang-zeyu Jun 11, 2022
8547c90
Adapt left/right layout container max heights
ang-zeyu Jun 12, 2022
facad3a
Fix overflow value
ang-zeyu Jun 12, 2022
aa9f60b
Docs update
ang-zeyu Jun 12, 2022
b9358fb
Remove temporary announcement banner
ang-zeyu Jun 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/_markbind/layouts/default.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<include src="headers/header.md" />
{% include "_markbind/layouts/headers/header.md" %}

<div id="flex-body">
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">
{{ content }}
</div>
</div>
Expand Down
8 changes: 4 additions & 4 deletions docs/_markbind/layouts/devGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<include src="headers/header.md" />
{% include "_markbind/layouts/headers/header.md" %}

<div id="flex-body">
<nav id="site-nav" class="fixed-header-padding">
<nav id="site-nav">
<div class="site-nav-top">
<div class="fw-bold mb-2" style="font-size: 1.25rem;">Developer Guide</div>
</div>
Expand All @@ -27,10 +27,10 @@
</site-nav>
</div>
</nav>
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">
{{ content }}
</div>
<nav id="page-nav" class="fixed-header-padding">
<nav id="page-nav">
<div class="nav-component slim-scroll">
<page-nav />
</div>
Expand Down
2 changes: 1 addition & 1 deletion docs/_markbind/layouts/headers/header.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
</head-bottom>

<header fixed>
<header sticky>
<navbar type="dark">
<a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand"><img src="{{baseUrl}}/images/logo-darkbackground.svg" height="20"></a>
<li><a highlight-on="exact" href="{{baseUrl}}/index.html" class="nav-link">HOME</a></li>
Expand Down
16 changes: 12 additions & 4 deletions docs/_markbind/layouts/userGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
<include src="headers/header.md" />
<div class="w-100 p-1 bg-warning text-center">

**This is a temporary "non-sticky" announcement that does not follow the header as you scroll down!**

Will be removed once PR is reviewed.
See [devGuide]({{baseUrl}}/devGuide/architecture.md) layout for "normal" usage without this announcement
</div>

{% include "_markbind/layouts/headers/header.md" %}

<div id="flex-body">
<nav id="site-nav" class="fixed-header-padding">
<nav id="site-nav">
<div class="site-nav-top">
<div class="fw-bold mb-2" style="font-size: 1.25rem;">User Guide</div>
</div>
Expand Down Expand Up @@ -44,10 +52,10 @@
</site-nav>
</div>
</nav>
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">
{{ content }}
</div>
<nav id="page-nav" class="fixed-header-padding">
<nav id="page-nav">
<div class="nav-component slim-scroll">
<page-nav />
</div>
Expand Down
16 changes: 5 additions & 11 deletions docs/css/main.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,28 +56,28 @@ mark {
margin: 0 auto;
min-width: 0;
max-width: 1000px;
overflow-x: auto;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documenting the layout file changes for review + future release changelog noting (should be simplified though I think =P)

1st of 3 important changes in the layout file:

This might be somewhat controversial, but is unfortunately necessary with a sticky header. At least, I haven't found another solution.

The issue (without this) occurs on pages that overflow (e.g. "formatting contents" page or "Using html javascript and css"). The nearest scrolling ancestor which is the page / root element expands to accomodate the overflown content, which in turn does 2 things:

  • window.innerWidth/Height are erroneous (although there is an easy alternative for this document.documentElement.clientWidth/Height)
  • More important is that the way sticky positioning is defined, the sticky positioning goes haywire (with or without our header height detection)

Gif demo (open image in new tab to view in order): there are 3 settings here.

  1. The first shows proper function of sticky positioning when the viewport zooms out to the entire page.
  2. The second showcases how the page loads on a mobile device normally, observe how the sticky positioning completely goes haywire as the page is "zoomed" (although it dosen't quite appear like that to the reader).
  3. The third is same as the second, except I temporarily toggled off the header hiding (the translateY) to show the issue is really unrelated to header hiding / anything we are doing.

stickyissues

You can try removing the overflow-x when testing this PR to see the issue better, its a little hard to present on a gif.

The fix: I've set overflow-x on the content wrapper which significantly changes ux on mobile devices (but just pages that overflow).

Pros:

Cons:

  • On desktop devices, although very very unlikely (since there is enough space for overflown content on mobile to fully "expand" - including our embeds), if there is overflow, I would still like to point out the horizontal scroll bar is only visible at the bottom of the content wrapper. (which can be confusing)
    • add to that that site development should usually be done on a desktop device (so authors will likely limit content sizes to a reasonable degree (e.g. images))
  • You'll no longer be able to "zoom out" on mobile (though arguably this could also be a plus for mobile ux)

Not sure if there's a better solution =, but imo its a good enough compromise.

padding: 0.8rem 20px 0 20px;
transition: 0.4s;
-webkit-transition: 0.4s;
}

#site-nav,
#page-nav {
display: flex;
flex-direction: column;
position: sticky;
top: 0;
top: var(--sticky-header-height);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2nd change per the docs

flex: 0 0 auto;
padding-top: 1rem;
max-width: 300px;
max-height: calc(100vh - var(--sticky-header-height));
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

last change: 100vh worked before as it took into account padding-top from fixed-header-padding.
With the shift to top: var(--sticky-header-height); the content boxes actually do shift down, so we need to minus that off.

The other changes (90vh) is just to standardise the way this is done in the layout stylesheet between the site and page nav to make things simpler.

width: 300px;
}

#site-nav {
display: flex;
flex-direction: column;
border-right: 1px solid lightgrey;
padding-bottom: 20px;
z-index: 999;
max-height: 100vh;
}

.site-nav-top {
Expand All @@ -90,13 +90,7 @@ mark {
}

#page-nav {
display: block;
border-left: 1px solid lightgrey;
max-height: 90vh;
}

#page-nav .nav-component {
max-height: 90vh;
}

@media screen and (max-width: 1299.98px) {
Expand Down
58 changes: 38 additions & 20 deletions docs/userGuide/tweakingThePageStructure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
<div id="layout-code-snippet">


```html {highlight-lines="{{ highlightLines or "1-4,7,31,36-44[:],49,54,67-71" }}"}
```html {highlight-lines="{{ highlightLines or "1-4,7[8:14],30[19:47],35-43[:],46[26:54],48,50[19:47],53,66-70" }}"}
{% raw %}<head-bottom>
<!-- Use head-top and head-bottom tags to insert content into the HTML <head> tag -->
<link rel="stylesheet" href="{{baseUrl}}/css/main.css">
</head-bottom>

<!-- Fix the header to the top while scrolling using the fixed attribute in a <header> tag -->
<header fixed>
<!-- Create a sticky header using the sticky attribute in a <header> tag -->
<header sticky>
<navbar type="dark">
<a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand">
<img src="{{baseUrl}}/images/logo-darkbackground.svg" height="20">
Expand All @@ -70,8 +70,7 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
</header>

<div id="flex-body">
<!-- Push content downward when using a fixed header with the fixed-header-padding class -->
<nav id="site-nav" class="fixed-header-padding">
<nav id="site-nav">
<div class="site-nav-top">
<div class="fw-bold mb-2" style="font-size: 1.25rem;">User Guide</div>
</div>
Expand All @@ -87,11 +86,11 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
</site-nav>
</div>
</nav>
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">
<!-- Insert the page's content into the layout using the {{ content }} variable -->
{{ content }}
</div>
<nav id="page-nav" class="fixed-header-padding">
<nav id="page-nav">
<div class="nav-component slim-scroll">
<!-- Insert a page navigation menu using the <page-nav /> component -->
<page-nav />
Expand Down Expand Up @@ -148,19 +147,38 @@ If you wish insert scripts at the bottom, before MarkBind's scripts, simply inse

---

### Fixing the header to the top

Headers are commonly included inside the HTML `<header>` tag. In encouraging this, a convenient interface to implement <tooltip content="Headers that stick to the top of the page while scrolling the content">fixed headers</tooltip> surrounding the `<header>` tag is provided that ensures page anchors work correctly.

****To fix the `<header>`****
1. Add the `fixed` attribute to your `<header>` element in the layout per the above example.

2. Then, to add the necessary top padding for the main content, add the `fixed-header-padding` class to **elements that should be shifted down** in accordance with the fixed header.

<box type="tip" seamless>

If you are not sure where to put the `fixed-header-padding` attribute, you may also refer to the default template for `markbind init`, which already has this setup.
</box>
### Sticking the header to the top

A sticky header can be implemented by simply adding the `sticky` attribute to a `<header>` element.

Using this attribute as opposed to setting `position: sticky` manually in your stylesheets comes with several conveniences:
- When scrolled to, page anchors will line up below the sticky header, and not hidden behind it.
- To preserve screen real estate, the header is hidden on devices with a width of less than 767px when the user scrolls down, and automatically re-shown when the page is scrolled up.

##### Offsetting elements with the header height

MarkBind also exposes the [css variable](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) `--sticky-header-height` which contains the height of your header.

It's primary intended use case is to offset secondary layout elements (e.g. your site navigation menu) so that they are not hidden behind the sticky header, as the reader scrolls down your page's main contents.

{{ icon_example }} Here's how it is used in the default layout's site and page navigation menus
```css
#site-nav,
#page-nav {
position: sticky;
/*
Offset the top sticky position,
such that the menus are not hidden behind the header.
*/
top: var(--sticky-header-height);
/*
Limit the height of the menus so that the reader is able to scroll
through the menus individually, without having to scroll to the bottom of the page.
*/
max-height: calc(100vh - var(--sticky-header-height));
...
}
```

---

Expand Down
6 changes: 3 additions & 3 deletions packages/cli/test/functional/test_site/_markbind/layouts/default.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,18 @@
<include src="headers/header.md" />

<div id="flex-body">
<nav id="site-nav" class="fixed-header-padding">
<nav id="site-nav">
<div class="site-nav-top">
<div class="fw-bold mb-2" style="font-size: 1.25rem;"><markdown>## {{ layoutName or "Default Layout" }}</markdown></div>
</div>
<div class="nav-component slim-scroll">
<include src="navigation/site-nav.md" />
</div>
</nav>
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">
{{ content }}
</div>
<nav id="page-nav" class="fixed-header-padding">
<nav id="page-nav">
<div class="nav-component slim-scroll">
<page-nav />
</div>
Expand Down
6 changes: 3 additions & 3 deletions packages/cli/test/functional/test_site/expected/bugs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@
<p><strong>Relative Link Test</strong> This is a relative Intra-Site link in a layout (see <a href="/test_site/index.html#heading-with-hidden-keyword">link</a>)</p>
</div>
<div id="flex-body">
<overlay-source id="site-nav" class="fixed-header-padding" tag-name="nav" to="site-nav">
<overlay-source id="site-nav" tag-name="nav" to="site-nav">
<div class="site-nav-top">
<div class="fw-bold mb-2" style="font-size: 1.25rem;">
<div>
Expand Down Expand Up @@ -206,7 +206,7 @@ <h3 id="testing-site-nav"><span id="testing-site-nav" class="anchor"></span>Test
</div>
</div>
</overlay-source>
<div id="content-wrapper" class="fixed-header-padding">
<div id="content-wrapper">

<div class="website-content">
<p><strong>Bug Description</strong></p>
Expand All @@ -216,7 +216,7 @@ <h3 id="testing-site-nav"><span id="testing-site-nav" class="anchor"></span>Test
</div>
<i class="fa fa-arrow-circle-up fa-lg d-print-none" id="scroll-top-button" onclick="handleScrollTop()" aria-hidden="true"></i>
</div>
<overlay-source id="page-nav" class="fixed-header-padding" tag-name="nav" to="page-nav">
<overlay-source id="page-nav" tag-name="nav" to="page-nav">
<div class="nav-component slim-scroll">
</div>
</overlay-source>
Expand Down
Loading