From d0d869e06b30a1f8b7b539978caa0ed6123f9864 Mon Sep 17 00:00:00 2001
From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
Date: Wed, 26 Aug 2020 00:17:32 +0200
Subject: Add breadcrumbs

Likewise, use relative links so that things work when just browsing
files locally without a server.

Next: tweak or remove redundant titles.
---
 repo/www/template.html | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'repo/www/template.html')

diff --git a/repo/www/template.html b/repo/www/template.html
index 724cde4..f2b308d 100644
--- a/repo/www/template.html
+++ b/repo/www/template.html
@@ -33,6 +33,11 @@ $include-before$
 $endfor$
 $if(title)$
 <header id="title-block-header">
+<nav class="breadcrumb" aria-label="Breadcrumb">
+<ol>
+$crumbs$
+</ol>
+</nav>
 <h1 class="title">$title$</h1>
 $if(subtitle)$
 <p class="subtitle">$subtitle$</p>
-- 
cgit v1.2.3


From 63a248e3dd9fc6857098c75ffbd49f72cf362c13 Mon Sep 17 00:00:00 2001
From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
Date: Fri, 28 Aug 2020 19:06:45 +0200
Subject: Make sure titles are not redundant with breadcrumbs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The logic for the various titles on any given page is:

    ∃README
        ∃title block
            <title>         ⇒ title block
            <header> <h1>   ⇒ title block
            TOC <h1>        ⇒ "Index for {target}"
        ∄title block
            <title>         ⇒ "{target}" or "README"
            <header> <h1>   ⇒ ∅
            TOC <h1>        ⇒ "Index for {target}"

    ∄README
        <title>         ⇒ "Index for {target}"
        <header> <h1>   ⇒ "Index"
        TOC <h1>        ⇒ ∅
---
 repo/www/Makefile          |  6 +++---
 repo/www/TODO              |  3 +--
 repo/www/generate-index.py | 39 ++++++++++++++++++++++-----------------
 repo/www/generate-page.py  |  4 ++--
 repo/www/helpers.py        | 10 ++++++----
 repo/www/template.html     |  4 ++--
 6 files changed, 36 insertions(+), 30 deletions(-)

(limited to 'repo/www/template.html')

diff --git a/repo/www/Makefile b/repo/www/Makefile
index 1f32115..6c41b45 100644
--- a/repo/www/Makefile
+++ b/repo/www/Makefile
@@ -53,6 +53,9 @@ site: $(pages) $(indices) $(stylesheets) $(stylesheets)
 # directories (e.g. folders that only contain subfolders).
 html_folders = $(call dirnames,$(pages) $(indices))
 
+top_index = $(OUT_DIR)/index.html
+subindices = $(filter-out $(top_index),$(indices))
+
 $(html_folders) $(stylesheets_dir) $(cache):
 	mkdir -p $@
 
@@ -67,9 +70,6 @@ $(pages): $(OUT_DIR)/%.html:
 		$(foreach s,$(stylesheets_src),--stylesheet style/$(s)) \
 		--template=$(html_template) $< $@
 
-top_index = $(OUT_DIR)/index.html
-subindices = $(filter-out $(top_index),$(indices))
-
 $(top_index): index_options =
 $(subindices): index_options = --site-title="$$(cat $(title))"
 
diff --git a/repo/www/TODO b/repo/www/TODO
index dd1e670..5759e87 100644
--- a/repo/www/TODO
+++ b/repo/www/TODO
@@ -1,6 +1,5 @@
 - compute "leak count" on toplevel index
-- autogenerate nav
-- autogenerate breadcrumbs
+- use "{pagetitle} - {sitetitle})" for <title>
 - get stylin'
     - pandoc template
     - tufte css? at least sidenotes rather than footnotes
diff --git a/repo/www/generate-index.py b/repo/www/generate-index.py
index a993c41..3bce69d 100755
--- a/repo/www/generate-index.py
+++ b/repo/www/generate-index.py
@@ -92,17 +92,14 @@ def main(arguments):
     folders, files = list_files(arguments.site_tree, target)
     pages, readme = list_pages(files)
 
+    toc_title = f'Index for {target}' if target else 'Index'
     html_toc = format_toc(folders, pages)
 
-    if target:
-        index_title = f'Index for {target}'
-        path_to_top = path.relpath('.', target)
-    else:
-        index_title = 'Index'
-        path_to_top = '.'
-
+    path_to_top = path.relpath('.', start=target)
     stylesheets = (path.join(path_to_top, s) for s in arguments.css)
+
     variables = {'crumbs': generate_crumbs(Path(target)/'index')}
+    metadata = {}
 
     if readme is not None:
         repo_top = Repo(search_parent_directories=True).working_dir
@@ -110,17 +107,20 @@ def main(arguments):
 
         # If the README doesn't have a title, give a default to pandoc
         # out-of-band.
-        page_title = None if has_title(readme_path) else 'README'
+        if not has_title(readme_path):
+            metadata['pagetitle'] = target or 'README'
 
         with NamedTemporaryFile(mode='w+') as toc:
-            toc.write('<h1>{title}</h1>\n'.format(title=index_title))
+            toc.write(f'<h1>{toc_title}</h1>\n')
             toc.write(html_toc)
             toc.flush()
 
-            pandoc(readme_path, arguments.output, arguments.template,
-                   arguments.filters, stylesheets, title=page_title,
-                   site_title=arguments.site_title, include_after=(toc.name,),
-                   variables=variables)
+            pandoc(
+                readme_path, arguments.output,
+                arguments.template, arguments.filters, stylesheets,
+                site_title=arguments.site_title, include_after=(toc.name,),
+                variables=variables, metadata=metadata
+            )
         return
 
     with NamedTemporaryFile(suffix='.md') as dummy_readme, \
@@ -128,10 +128,15 @@ def main(arguments):
         toc.write(html_toc)
         toc.flush()
 
-        pandoc(dummy_readme.name, arguments.output, arguments.template,
-               arguments.filters, stylesheets, title=index_title,
-               site_title=arguments.site_title, include_after=(toc.name,),
-               variables=variables)
+        metadata['pagetitle'] = toc_title
+        metadata['title'] = 'Index'
+
+        pandoc(
+            dummy_readme.name, arguments.output,
+            arguments.template, arguments.filters, stylesheets,
+            site_title=arguments.site_title, include_after=(toc.name,),
+            variables=variables, metadata=metadata
+        )
 
 
 if __name__ == '__main__':
diff --git a/repo/www/generate-page.py b/repo/www/generate-page.py
index 8036cc5..967689e 100755
--- a/repo/www/generate-page.py
+++ b/repo/www/generate-page.py
@@ -50,9 +50,9 @@ def main(arguments):
         arguments.template,
         arguments.filters,
         stylesheets,
-        title=arguments.title,
         site_title=arguments.site_title,
-        variables={'crumbs': generate_crumbs(page_path)}
+        variables={'crumbs': generate_crumbs(page_path)},
+        metadata={'pagetitle':arguments.title}
     )
 
 
diff --git a/repo/www/helpers.py b/repo/www/helpers.py
index 80b8857..3d412b4 100644
--- a/repo/www/helpers.py
+++ b/repo/www/helpers.py
@@ -56,8 +56,8 @@ def deserialize_directories(directories):
     }
 
 
-def pandoc(page, output, template, filters, stylesheets, title=None,
-           site_title=None, include_after=(), variables=None):
+def pandoc(page, output, template, filters, stylesheets, site_title=None,
+           include_after=(), variables=None, metadata=None):
     cmd = (
         'pandoc', '-s', page, '-o', output, '--template', template,
         *chain(*(('--lua-filter', f) for f in filters)),
@@ -65,14 +65,16 @@ def pandoc(page, output, template, filters, stylesheets, title=None,
         *chain(*(('--include-after-body', f) for f in include_after))
     )
 
-    if title is not None:
-        cmd += ('-M', f'title={title}')
     if site_title is not None:
         cmd += ('-T', site_title)
     if variables is not None:
         cmd += tuple(chain(
             *(('-V', f'{k}={v}') for k, v in variables.items())
         ))
+    if metadata is not None:
+        cmd += tuple(chain(
+            *(('-M', f'{k}={v}') for k, v in metadata.items())
+        ))
 
     environ['LUA_PATH'] = '.cache/?.lua;;'
     run(cmd, check=True)
diff --git a/repo/www/template.html b/repo/www/template.html
index f2b308d..3417e93 100644
--- a/repo/www/template.html
+++ b/repo/www/template.html
@@ -31,14 +31,15 @@ $endfor$
 $for(include-before)$
 $include-before$
 $endfor$
-$if(title)$
 <header id="title-block-header">
 <nav class="breadcrumb" aria-label="Breadcrumb">
 <ol>
 $crumbs$
 </ol>
 </nav>
+$if(title)$
 <h1 class="title">$title$</h1>
+$endif$
 $if(subtitle)$
 <p class="subtitle">$subtitle$</p>
 $endif$
@@ -49,7 +50,6 @@ $if(date)$
 <p class="date">$date$</p>
 $endif$
 </header>
-$endif$
 $if(toc)$
 <nav id="$idprefix$TOC" role="doc-toc">
 $if(toc-title)$
-- 
cgit v1.2.3


From b6cb7d009364ab63e09fe6febc15330edae0644a Mon Sep 17 00:00:00 2001
From: Kévin Le Gouguec <kevin.legouguec@gmail.com>
Date: Fri, 28 Aug 2020 22:21:11 +0200
Subject: Move site title after page title

Plenty of websites do this; on GNU/Linux most applications do this; I
guess the goal is to make the most specific information go first, so
that tabs remain identifiable as they become narrower.
---
 repo/www/TODO              | 1 -
 repo/www/generate-index.py | 6 ++++--
 repo/www/generate-page.py  | 4 ++--
 repo/www/helpers.py        | 6 ++----
 repo/www/template.html     | 2 +-
 5 files changed, 9 insertions(+), 10 deletions(-)

(limited to 'repo/www/template.html')

diff --git a/repo/www/TODO b/repo/www/TODO
index 5759e87..cd97605 100644
--- a/repo/www/TODO
+++ b/repo/www/TODO
@@ -1,5 +1,4 @@
 - compute "leak count" on toplevel index
-- use "{pagetitle} - {sitetitle})" for <title>
 - get stylin'
     - pandoc template
     - tufte css? at least sidenotes rather than footnotes
diff --git a/repo/www/generate-index.py b/repo/www/generate-index.py
index 3bce69d..16d1874 100755
--- a/repo/www/generate-index.py
+++ b/repo/www/generate-index.py
@@ -100,6 +100,8 @@ def main(arguments):
 
     variables = {'crumbs': generate_crumbs(Path(target)/'index')}
     metadata = {}
+    if arguments.site_title is not None:
+        metadata['sitetitle'] = arguments.site_title
 
     if readme is not None:
         repo_top = Repo(search_parent_directories=True).working_dir
@@ -118,7 +120,7 @@ def main(arguments):
             pandoc(
                 readme_path, arguments.output,
                 arguments.template, arguments.filters, stylesheets,
-                site_title=arguments.site_title, include_after=(toc.name,),
+                include_after=(toc.name,),
                 variables=variables, metadata=metadata
             )
         return
@@ -134,7 +136,7 @@ def main(arguments):
         pandoc(
             dummy_readme.name, arguments.output,
             arguments.template, arguments.filters, stylesheets,
-            site_title=arguments.site_title, include_after=(toc.name,),
+            include_after=(toc.name,),
             variables=variables, metadata=metadata
         )
 
diff --git a/repo/www/generate-page.py b/repo/www/generate-page.py
index 967689e..cb2317b 100755
--- a/repo/www/generate-page.py
+++ b/repo/www/generate-page.py
@@ -50,9 +50,9 @@ def main(arguments):
         arguments.template,
         arguments.filters,
         stylesheets,
-        site_title=arguments.site_title,
         variables={'crumbs': generate_crumbs(page_path)},
-        metadata={'pagetitle':arguments.title}
+        metadata={'pagetitle': arguments.title,
+                  'sitetitle': arguments.site_title}
     )
 
 
diff --git a/repo/www/helpers.py b/repo/www/helpers.py
index 3d412b4..48ebccf 100644
--- a/repo/www/helpers.py
+++ b/repo/www/helpers.py
@@ -56,8 +56,8 @@ def deserialize_directories(directories):
     }
 
 
-def pandoc(page, output, template, filters, stylesheets, site_title=None,
-           include_after=(), variables=None, metadata=None):
+def pandoc(page, output, template, filters, stylesheets, include_after=(),
+           variables=None, metadata=None):
     cmd = (
         'pandoc', '-s', page, '-o', output, '--template', template,
         *chain(*(('--lua-filter', f) for f in filters)),
@@ -65,8 +65,6 @@ def pandoc(page, output, template, filters, stylesheets, site_title=None,
         *chain(*(('--include-after-body', f) for f in include_after))
     )
 
-    if site_title is not None:
-        cmd += ('-T', site_title)
     if variables is not None:
         cmd += tuple(chain(
             *(('-V', f'{k}={v}') for k, v in variables.items())
diff --git a/repo/www/template.html b/repo/www/template.html
index 3417e93..b4746d9 100644
--- a/repo/www/template.html
+++ b/repo/www/template.html
@@ -13,7 +13,7 @@ $endif$
 $if(keywords)$
   <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
 $endif$
-  <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+  <title>$pagetitle$$if(sitetitle)$ – $sitetitle$$endif$</title>
   <style>
     $styles.html()$
   </style>
-- 
cgit v1.2.3