Merge pull request #87 from carpentries/allow-overview-pages

Allow overview pages
carpentries · Sep 1, 2023 · 8b93052 · 8b93052
2 parents fe0635f + b291512
commit 8b93052
Show file tree

Hide file tree

Showing 14 changed files with 309 additions and 84 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,28 @@
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{qmd,Rmd,md}]
+indent_size = 2
+indent_style = space
+max_line_length = 80  # Please keep this in sync with bin/lesson_check.py!
+trim_trailing_whitespace = false  # keep trailing spaces in markdown - 2+ spaces are translated to a hard break (<br/>)
+
+[*.r]
+max_line_length = 80
+indent_size = 2
+indent_style = space
+
+[*.{py,js}]
+indent_size = 4
+indent_style = space
+max_line_length = 80
+
+[*.sh]
+end_of_line = lf
+
+[Makefile]
+indent_style = tab
diff --git a/NEWS.md b/NEWS.md
@@ -1,9 +1,23 @@
 # varnish 0.3.0
 
-* The `spoiler` dropdown item has been implemented (implemented: @tobyhodges,
-  #92)
-* The build process for css and javascript has been localised to node dev
-  dependencies.
+* Lesson overview pages are now supported (reported: @zkamvar,
+  https://github.com/carpentries/workbench/issues/65; implemented: @zkamvar,
+  #87). These overview pages do not have a sidebar and have extra navigation
+  back to home and the setup page in the menu bar.
+- new 'overview' template is implemented to always contain links back to the
+  home page.
+* The `spoiler` dropdown item has been implemented to allow authors to create
+  stand-alone accordions that will hide optinal content from users without using
+  a `solution` class (implemented: @tobyhodges, #92)
+
+## MISC
+
+* The build process for css/js bundles is now self-contained in the node
+  dev dependencies. Running `npm install` will install everything needed to
+  re-compile the js and css.
+* The README has been updated with instructions to build locally
+* An `.editorconfig` file has been added to ensure the JS content is indented
+  properly
 
 # varnish 0.2.18
 

diff --git a/README.md b/README.md
@@ -25,14 +25,36 @@ copy the styling and templates to your lesson website.
 
 ## CSS and JavaScript
 
-The CSS and JavaScript used for the lessons are minified. Their sources live in
-the [`source/`](source/) folder with directives to include their dependencies
-(bootstrap, jquery, feather).
+The CSS and JavaScript used for the lessons are minified using SASS and
+uglifyjs. Their sources live in the [`source/`](source/) folder with directives
+to include their dependencies (bootstrap, jquery, feather).
 
 The minified versions are built via GitHub actions any time one of the source
 files is changed. 
 
-Instructions to build locally forthcoming.
+To build this locally, you need to make sure to have a working version of
+`node` and `npm`, which can be installed [via the node version manager, nvm](https://github.com/nvm-sh/nvm#intro).
+
+### Install dependencies
+
+Once you have `nvm` installed, you can install the node packages locally (they
+will install in the _`node_modules/`_ directory and will be ignored by git)
+with the following command:
+
+```sh
+nvm install 16 # make sure we are using node version 16
+npm install    # install the packages defined in package.json
+```
+
+### Minify CSS and JS
+
+Once you have the dependencies installed, you can run the following scripts to
+minify the CSS and JS:
+
+```sh
+bash squash-sass.sh     # use the sass node module to compile CSS
+bash squash-a-script.sh # use the uglifyjs node module to compile JS
+```
 
 ## HTML Templates
 
@@ -42,6 +64,8 @@ We have customized the following templates:
  - [content-syllabus] is the landing page for the lessons
  - [content-extra] is used for pages that are not chapters and do not need
    positional navigation
+ - [content-overview] is like content-extra, but is meant for the home page of
+   an overview lesson
  - [head] contains the metadata and script loading
  - [navbar] is a bit of misnomer, but it contains the sidebar navigation
  - [header] contains metadata and favicons

diff --git a/inst/pkgdown/assets/assets/scripts.js b/inst/pkgdown/assets/assets/scripts.js
diff --git a/inst/pkgdown/assets/assets/styles.css b/inst/pkgdown/assets/assets/styles.css
diff --git a/inst/pkgdown/assets/assets/styles.css.map b/inst/pkgdown/assets/assets/styles.css.map
diff --git a/inst/pkgdown/templates/content-chapter.html b/inst/pkgdown/templates/content-chapter.html
@@ -8,15 +8,21 @@
         {{/page_back}}
         {{#page_forward}}
         <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}">Next<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
-      </div>
         {{/page_forward}}
+      </div>
       <!-- content for large screens -->
       <div class="d-none d-sm-none d-md-block">
         {{#page_back}}
-        <a class="chapter-link" href="{{#site}}{{root}}{{/site}}{{page_back}}" rel="prev"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Previous{{#back_title}}: {{back_title}}{{/back_title}}</a>
+        <a class="chapter-link" href="{{#site}}{{root}}{{/site}}{{page_back}}" rel="prev">
+          <i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>
+          {{#back_title}}Previous: {{back_title}}{{/back_title}}{{^back_title}}Home{{/back_title}}
+        </a>
         {{/page_back}}
         {{#page_forward}}
-        <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}" rel="next">Next{{#forward_title}}: {{forward_title}}{{/forward_title}}... <i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
+        <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}" rel="next">
+          {{#forward_title}}Next: {{forward_title}}... {{/forward_title}}{{^forward_title}}Home{{/forward_title}}
+          <i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i>
+        </a>
         {{/page_forward}}
       </div>
       <hr/>
@@ -60,10 +66,16 @@ <h1>{{& pagetitle}}</h1>
       <!-- content for large screens -->
       <div class="d-none d-sm-none d-md-block">
         {{#page_back}}
-        <a class="chapter-link" href="{{#site}}{{root}}{{/site}}{{page_back}}" rel="prev"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Previous{{#back_title}}: {{back_title}}{{/back_title}}</a>
+        <a class="chapter-link" href="{{#site}}{{root}}{{/site}}{{page_back}}" rel="prev">
+          <i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>
+          {{#back_title}}Previous: {{back_title}}{{/back_title}}{{^back_title}}Home{{/back_title}}
+        </a>
         {{/page_back}}
         {{#page_forward}}
-        <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}" rel="next">Next{{#forward_title}}: {{forward_title}}{{/forward_title}}... <i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
+        <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}" rel="next">
+          {{#forward_title}}Next: {{forward_title}}... {{/forward_title}}{{^forward_title}}Home{{/forward_title}}
+          <i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i>
+        </a>
         {{/page_forward}}
       </div>
     </nav>

diff --git a/inst/pkgdown/templates/content-extra.html b/inst/pkgdown/templates/content-extra.html
@@ -1,5 +1,20 @@
 <!-- START: inst/pkgdown/templates/content-extra.html -->
   <div class="col-xl-8 col-lg-12 primary-content">
+    {{#overview}}
+    <nav class="lesson-content mx-md-4" aria-label="Home Page Navigation">
+      <!-- content for small screens -->
+      <div class="d-block d-sm-block d-md-none">
+        <a class="chapter-link" href="index.html"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Home</a>
+        <a class="chapter-link float-end" href="index.html">Home<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
+      </div>
+      <!-- content for large screens -->
+      <div class="d-none d-sm-none d-md-block">
+        <a class="chapter-link" href="index.html"><i aria-hidden="true" class="small-arrow" data-feather="arrow-left"></i>Home</a>
+        <a class="chapter-link float-end" href="index.html">Home<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
+      </div>
+      <hr/>
+    </nav>
+    {{/overview}}
     <main id="main-content" class="main-content">
       <div class="container lesson-content">
         <h1>{{{pagetitle}}}</h1>

diff --git a/inst/pkgdown/templates/content-overview.html b/inst/pkgdown/templates/content-overview.html
@@ -0,0 +1,38 @@
+<!-- START: inst/pkgdown/templates/content-syllabus.html -->
+<div class="col-xl-12 col-lg-12">
+    <main id="main-content" class="main-content">
+      <h1>{{{pagetitle}}}</h1>
+      <div class="container lesson-content">
+        <p>
+          {{#updated}} Last updated on {{updated}} | {{/updated}}
+          <a href="{{#yaml}}{{source}}/edit/{{branch}}/{{/yaml}}{{file_source}}{{^file_source}}index.md{{/file_source}}">
+            Edit this page <i aria-hidden="true" data-feather="edit"></i>
+          </a>
+        </p>
+
+      {{{readme}}}
+
+      {{#syllabus}}
+      <section id="schedule">
+      <table class="table schedule table-striped" role="presentation">
+        <tbody>
+          {{#setup}}
+          <tr>
+            <td></td><td><a href="#setup">Setup Instructions</a></td><td> Download files required for the lesson</td>
+          </tr>
+          {{/setup}}
+          {{{syllabus}}}
+      </table>
+      <p>
+      The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.
+      </p>
+      </section>
+      {{/syllabus}}
+      {{#setup}}
+      <section id="setup">
+      {{{setup}}}
+      </section>
+      {{/setup}}
+    </main>
+  </div>
+<!-- END  : inst/pkgdown/templates/content-syllabus.html -->
diff --git a/inst/pkgdown/templates/content-syllabus.html b/inst/pkgdown/templates/content-syllabus.html
@@ -5,8 +5,8 @@
       <div class="d-block d-sm-block d-md-none">
         {{#page_forward}}
         <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}">Next<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
-      </div>
         {{/page_forward}}
+      </div>
       <!-- content for large screens -->
       <div class="d-none d-sm-none d-md-block">
         {{#page_forward}}
@@ -45,8 +45,8 @@ <h1 class="schedule-heading">{{{pagetitle}}}</h1>
       <div class="d-block d-sm-block d-md-none">
         {{#page_forward}}
         <a class="chapter-link float-end" href="{{#site}}{{root}}{{/site}}{{page_forward}}">Next<i aria-hidden="true" class="small-arrow" data-feather="arrow-right"></i></a>
-      </div>
         {{/page_forward}}
+      </div>
       <!-- content for large screens -->
       <div class="d-none d-sm-none d-md-block">
         {{#page_forward}}

diff --git a/inst/pkgdown/templates/header.html b/inst/pkgdown/templates/header.html
@@ -35,7 +35,7 @@
         {{/life_cycle}}{{/yaml}}
       </div>
     </div>
-    <div class="selector-container ">
+    <div class="selector-container">
       {{#yaml}}{{#workbench-beta}}
       <div class="beta-alert alert alert-light alert-dismissable fade show" role="alert">
         {{#pre-beta-date}}
@@ -59,8 +59,8 @@
         {{^beta-date}}{{^pre-beta-date}}
         <i aria-hidden="true" class="icon" data-feather="alert-circle" style="color: #5bbad5"></i>
         {{/pre-beta-date}}{{/beta-date}}
-        Workbench Beta | 
-        <a href="https://carpentries.typeform.com/to/KRBl4IZM" class="alert-link" style="text-decoration: wavy overline">Give Feedback</a> | 
+        Workbench Beta |
+        <a href="https://carpentries.typeform.com/to/KRBl4IZM" class="alert-link" style="text-decoration: wavy overline">Give Feedback</a> |
         <a href="https://carpentries.github.io/workbench/beta-phase.html" class="alert-link">Learn More</a>
         <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
       </div>
@@ -122,21 +122,34 @@
             {{#site}}{{title}}{{/site}}
           </span>
         </li>
+        {{#overview}}
+        {{! We want to include a setup link prominently in the resources for overview pages }}
+        <li>
+          {{! NOTE: the reason why we do not use the site root here is because we would need to set the site context _before_ overview }}
+          <a class="nav-link" href="index.html#setup">Setup</a>
+        </li>
+        {{/overview}}
         {{#instructor}}
+        {{^overview}}
         <li class="nav-item">
           <a class="nav-link" href="{{#site}}{{root}}{{/site}}instructor/key-points.html">Key Points</a>
         </li>
+        {{/overview}}
         <li class="nav-item">
           <a class="nav-link" href="{{#site}}{{root}}{{/site}}instructor/instructor-notes.html">Instructor Notes</a>
         </li>
+        {{^overview}}
         <li class="nav-item">
           <a class="nav-link" href="{{#site}}{{root}}{{/site}}instructor/images.html">Extract All Images</a>
         </li>
+        {{/overview}}
         {{/instructor}}
         {{^instructor}}
+        {{^overview}}
         <li class="nav-item">
           <a class="nav-link" href="{{#site}}{{root}}{{/site}}key-points.html">Key Points</a>
         </li>
+        {{/overview}}
         <li class="nav-item">
           <a class="nav-link" href="{{#site}}{{root}}{{/site}}reference.html#glossary">Glossary</a>
         </li>
@@ -158,7 +171,7 @@
     </div>
     <form class="d-flex col-md-2 search-form">
       <fieldset disabled>
-      <input class="form-control me-2 searchbox" type="search" placeholder="Search" aria-label="Search"> 
+      <input class="form-control me-2 searchbox" type="search" placeholder="Search" aria-label="Search">
         <button class="btn btn-outline-success tablet-search-button"  type="submit">
           <i class="search-icon" data-feather="search" role="img" aria-label="search button"></i>
         </button>
@@ -171,6 +184,7 @@
   {{#site}}{{title}}{{/site}}
 </div>
 
+{{^overview}}
 <aside class="col-md-12 lesson-progress">
   <div style="width: {{progress}}%" class="percentage">
     {{progress}}%
@@ -180,3 +194,4 @@
     </div>
   </div>
 </aside>
+{{/overview}}