howdoc 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9201c07602657e340541387ddb7704ca43fcde6183ce52fd1273f036dd87513b
-  data.tar.gz: 2f9bc01470635e9d626141909f12196cb950e41e80c11077aa78943216291259
+  metadata.gz: 87dfef0ef3ca14057c666eaa64c003057f7b7f8ba17cb1f992375c4add7358e6
+  data.tar.gz: 5a3f3ecfccd3e57262e00b434ba69d79874251d25e74b527e8a6d03754e5c0ef
 SHA512:
-  metadata.gz: c970647ba28984988f284e173b3a675123cee78b35a66a1c0ff8c5d7ed4d6ca856e41dbf3b7e8eade8a4b852121a636d86869d1f002007f5df3eba6b5c9ab10a
-  data.tar.gz: ea877687bd2a0ef1c550769f96d5cfea425ccda4f74ee1d4d71dde7575f5f473c13e97a13998d71f9958d01aa6fbeed69ca3daeb056ad0448e32f5f2ab42d3a9
+  metadata.gz: 80ffc63f82dd61163966cd9afa236ff758b29ad02bf1dcf54486d41db1fcdee943bcbd337d0966a9a6c69aae624355d43b732164ac31425483dabc9c395812d0
+  data.tar.gz: 756e73c34a33a1a4b5cdb0b41f4cf2143414c3b97bc30096e62511d38961ff8cc07b44ba9e35c2956b0cb0e942bd9d669bb8574ec2d578a6dba368c8dce5135d

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.0
+
+The menu now fits a phone. Twenty guides listed above the page filled the
+screen before the guide a reader had come for began, so a narrow screen folds
+the list away behind a line they can tap, and a wide one, which has room for it
+beside the page, shows it exactly as before.
+
+- The menu on a narrow screen is a slim bar carrying the name of the
+  documentation set, the languages and one line to open the guides
+  (`howdoc.nav.guides`). It follows the reader down the page while the list is
+  folded, and steps out of the way while it is open.
+- The index is the one page whose menu is the page, so there the list is open
+  from the start and follows the heading that says what the guides are for
+  instead of pushing it under twenty links.
+- Only `shared/html/nav.haml` and the stylesheet changed, so an application
+  with a menu template of its own keeps what it has.
+
 ## 0.4.0
 
 Screenshots can now show what the step is about, the way a guide made by hand

data/README.md

@@ -263,6 +263,11 @@ an empty placeholder and the index pass -- which has just read every page back
 
 Both are optional. A template that carries neither is left exactly as it is.
 
+Above the page rather than beside it -- a phone, a narrow window -- the list of
+guides folds away behind a line the reader taps, so the guide begins where the
+screen begins. The stylesheet unfolds it again where there is room beside the
+page, and the index, whose menu is the page, is open from the start.
+
 The menu also links the same guide in every other language the application
 publishes. Guides are matched by their identifier rather than their file name,
 because a translated heading gives a translated file name, and each language

data/config/locales/howdoc.en.yml

@@ -21,6 +21,8 @@ en:
       follow_steps: 'Follow these steps:'
     languages:
       en: English
+    nav:
+      guides: All guides
     pager:
       next: Next
       previous: Previous

data/config/locales/howdoc.et.yml

@@ -21,6 +21,8 @@ et:
       follow_steps: 'Palun jälgige järgnevaid samme:'
     languages:
       et: Eesti
+    nav:
+      guides: Kõik juhendid
     pager:
       next: Järgmine
       previous: Eelmine

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/templates/default/assets/howdoc.css

@@ -31,6 +31,12 @@ body.howdoc {
   padding: 3rem 1.25rem 6rem;
 }
 
+/* The index ends where its menu begins, so the space below it is the menu's
+   to give. */
+.howdoc-index {
+  padding-bottom: 1.5rem;
+}
+
 .howdoc h1 {
   margin: 0 0 1rem;
   font-size: 1.9rem;
@@ -68,7 +74,7 @@ body.howdoc {
 
 .howdoc-toc {
   list-style: none;
-  margin: 1.5rem 0 0;
+  margin: 1rem 0 0;
   padding: 0;
 }
 
@@ -96,19 +102,84 @@ body.howdoc {
   text-decoration: underline;
 }
 
-/* The menu sits beside the page it belongs to, and above it when there is no
-   room beside. A guide written before the index pass has an empty menu, and an
-   empty menu is no menu at all. */
+/* The menu sits beside the page it belongs to, and folded above it when there
+   is no room beside. A guide written before the index pass has an empty menu,
+   and an empty menu is no menu at all. */
 .howdoc-nav:empty,
 .howdoc-pager:empty {
   display: none;
 }
 
+/* Above the page, the menu is a slim bar the reader keeps within reach
+   wherever they have scrolled to, with the guides folded away behind a line
+   they can tap. Unfolded, the list is taller than the screen, so the bar stops
+   following along and scrolls away with the page like anything else. */
 .howdoc-nav {
-  padding: 1.5rem 1.25rem;
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: var(--howdoc-bg);
+  padding: 0.9rem 1.25rem 1rem;
   border-bottom: 1px solid var(--howdoc-rule);
 }
 
+.howdoc-nav:has(.howdoc-nav-guides[open]) {
+  position: static;
+}
+
+/* The index is the one page whose menu is the page, so its menu is open and
+   there is nothing to fold. It comes after the heading that says what the
+   guides are for, rather than pushing that heading under twenty links. */
+body.howdoc {
+  display: flex;
+  flex-direction: column;
+}
+
+.howdoc-nav-index {
+  order: 1;
+}
+
+/* Nothing to fold on the index: the list is the page, so the line that would
+   fold it away is not offered there. */
+.howdoc-nav-index .howdoc-nav-summary {
+  display: none;
+}
+
+.howdoc-nav-summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-top: 0.75rem;
+  padding: 0.55rem 0.85rem;
+  border: 1px solid var(--howdoc-rule);
+  border-radius: 8px;
+  color: var(--howdoc-fg);
+  font-size: 0.95rem;
+  font-weight: 600;
+  cursor: pointer;
+  list-style: none;
+}
+
+.howdoc-nav-summary::-webkit-details-marker {
+  display: none;
+}
+
+/* The chevron that says the line can be tapped: down while the list is folded,
+   up while it is not. */
+.howdoc-nav-summary::after {
+  content: '';
+  width: 0.45rem;
+  height: 0.45rem;
+  border-right: 2px solid var(--howdoc-muted);
+  border-bottom: 2px solid var(--howdoc-muted);
+  transform: translateY(-0.15rem) rotate(45deg);
+}
+
+.howdoc-nav-guides[open] > .howdoc-nav-summary::after {
+  transform: translateY(0.15rem) rotate(-135deg);
+}
+
 @media (min-width: 60rem) {
   body.howdoc {
     display: grid;
@@ -116,15 +187,39 @@ body.howdoc {
     align-items: start;
   }
 
-  .howdoc-nav {
+  .howdoc-nav,
+  .howdoc-nav:has(.howdoc-nav-guides[open]) {
     position: sticky;
     top: 0;
+    z-index: auto;
     max-height: 100vh;
     overflow-y: auto;
     padding: 2rem 1.25rem 3rem;
     border-right: 1px solid var(--howdoc-rule);
     border-bottom: 0;
   }
+
+  .howdoc-nav-index {
+    order: 0;
+  }
+
+  /* Beside the page there is room for the whole list, so the fold is undone:
+     the line to tap goes away and every guide is shown whether the reader ever
+     tapped it or not. Two rules for two kinds of browser -- the older kind
+     folds content away by not displaying it, the newer kind through
+     ::details-content. */
+  .howdoc-nav-summary {
+    display: none;
+  }
+
+  .howdoc-nav-guides > *:not(summary) {
+    display: block;
+  }
+
+  .howdoc-nav-guides::details-content {
+    content-visibility: visible;
+    block-size: auto;
+  }
 }
 
 .howdoc-nav-head {

data/templates/default/shared/html/nav.haml

@@ -2,7 +2,7 @@
 -# no other guide exists yet -- so a guide leaves the empty <nav> below and the
 -# index pass fills it in once every guide is on disk. The index renders it
 -# directly, because by then it knows.
-%nav.howdoc-nav{ data: { howdoc_nav: true } }
+%nav.howdoc-nav{ class: ('howdoc-nav-index' if @current.nil?), data: { howdoc_nav: true } }
   .howdoc-nav-head
     %a.howdoc-nav-home{ href: './index.html' }= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
     - if @languages.size > 1
@@ -13,13 +13,20 @@
               %a{ href: language[:href], lang: language[:code] }= language[:label]
             - else
               %span{ lang: language[:code] }= language[:label]
-  %ul.howdoc-toc
-    - previous_group = nil
-    - @records.each do |record|
-      - group = @config.group_label.call(record)
-      - if group && group != previous_group
-        %li.howdoc-toc-group= group
-        - previous_group = group
-      - current = @current && record.filename == @current.filename
-      %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
-        %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading
+  -# On a phone a list of twenty guides fills the screen before the guide the
+  -# reader came to read has begun, so the list is folded away behind a line
+  -# they can tap. A wide screen has room for it beside the page and unfolds it
+  -# again in the stylesheet. The index is the one page whose menu is the page,
+  -# so there it is open from the start.
+  %details.howdoc-nav-guides{ open: @current.nil? }
+    %summary.howdoc-nav-summary= Howdoc::Narrator.phrase(:nav, :guides, locale: @locale)
+    %ul.howdoc-toc
+      - previous_group = nil
+      - @records.each do |record|
+        - group = @config.group_label.call(record)
+        - if group && group != previous_group
+          %li.howdoc-toc-group= group
+          - previous_group = group
+        - current = @current && record.filename == @current.filename
+        %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
+          %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Priit Tark