v1.3.0 (#274)

Closes #272 
Closes #269 
Closes #191  (hopefully)

New template version checklist:

- [x] I have updated CITATION and CHANGELOG as appropriate.
- [x] I have updated lab-website-template-docs as appropriate. Pending
change request:
https://greene-lab.gitbook.io/lab-website-template-docs/~/changes/a57wjuxagDtJUR241kyt/basics/components/list
- [x] I have checked the testbed as appropriate.

---

- use `name` field for all debug/logging steps in workflows
- use `jwalton/gh-find-current-pr` to get PR number to be more reliable
(in rare cases, `github.event.number` can be empty)
- fix bug in "first time setup" workflow where `description` gets
appended to `user` due to missing `\n` in printf
- rename workflows from `.yml` to `.yaml` for consistency
- remove useless "build preview" workflow run in "on schedule" †
- dont run "update citations" workflow on PR close, which should
hopefully avoid issues discussed in #191. in my testing on a fork
(vincerubinetti/lab-website-template), it does. need to use step-level
`if` skipping instead of job-level or workflow-level because of [this
issue](actions/runner#491 (comment)).
- when "on schedule" workflow opens a PR, add hint in body of the PR on
how to trigger the live preview workflow
- use the `xml_escape` liquid filter wherever a user/third-party
provided field is used in an HTML attribute to prevent special
characters breaking HTML rendering. example: `aria-label="{{
citation.title }}"` and `citation.title` is `"Lorem Ipsum" dataset`,
causing attribute to prematurely close.
- change `data_filter` to accept Ruby expressions instead of custom
syntax. use Ruby `eval` and define each field in the item as a local
variable, e.g. `{"animal": "cat"}` lets you use `filter="animal ==
'cat'"`.
- fix heading anchor styles
- add styles for `<details>` element
- fix logo shrinking/growing css bugs

† due to a [github
limitation](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs),
it wouldn't not run anyway on the auto-created PR. the user must
close/reopen the PR, then the regular "on pr" workflow (which includes
running "build preview") will run. i've already [updated the docs to
talk about
this](https://greene-lab.gitbook.io/lab-website-template-docs/basics/citations#periodic-updates).
from now on, let's treat auto-opening PR as the only supported way.
previously i considered that the user could change `open-pr` to `false`
to have "on schedule" commit updated citations directly to `main`, but
let's nix that to maintain simplicity. it's probably better that we
force the user to review the changes before pushing them to their live
site anyway. if we did want to support that in the future, the "build
preview" run i removed would have to be changed to a "build site", since
we'd want to be re-building the `main` branch version of the site, not a
preview for a PR.

---------

Co-authored-by: Faisal Alquaddoomi <[email protected]>

.github/workflows/build-preview.yaml

@@ -21,8 +21,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Checkout branch contents
         uses: actions/checkout@v4
@@ -42,14 +42,22 @@ jobs:
         id: pages
         uses: actions/configure-pages@v4
 
-      # for debugging
-      - if: runner.debug == '1'
+      - uses: jwalton/gh-find-current-pr@master
+        if: github.event.action != 'closed'
+        id: pr
+        with:
+          state: all
+
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       - name: Build preview version of site
         if: github.event.action != 'closed'
         run: |
-          JEKYLL_ENV=production bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path || '' }}/${{ env.PREVIEWS_FOLDER }}/pr-${{ github.event.number }}"
+          JEKYLL_ENV=production bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path || '' }}/${{ env.PREVIEWS_FOLDER }}/pr-${{ env.pr }}"
+        env:
+          pr: ${{ steps.pr.outputs.pr }}
 
       - name: Commit preview to Pages branch
         uses: rossjrw/[email protected]

.github/workflows/build-site.yaml

@@ -20,8 +20,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Checkout branch contents
         uses: actions/checkout@v4
@@ -36,8 +36,8 @@ jobs:
         id: pages
         uses: actions/configure-pages@v4
 
-      # for debugging
-      - if: runner.debug == '1'
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       - name: Set root url

.github/workflows/first-time-setup.yaml

@@ -13,8 +13,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Create Pages branch
         uses: peterjgrainger/[email protected]
@@ -28,8 +28,8 @@ jobs:
         with:
           ref: gh-pages
 
-      # for debugging
-      - if: runner.debug == '1'
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       # clean slate, as if starting from orphan branch
@@ -70,8 +70,8 @@ jobs:
         run: |
           user="${{ github.repository_owner }}"
           description="An engaging 1-3 sentence description of your lab."
-          printf "USER=${user}" >> $GITHUB_ENV
-          printf "DESCRIPTION=${description}" >> $GITHUB_ENV
+          printf "\nUSER=${user}" >> $GITHUB_ENV
+          printf "\nDESCRIPTION=${description}" >> $GITHUB_ENV
 
       - name: Personalize readme for user
         run: |

.github/workflows/on-schedule.yaml

@@ -20,8 +20,3 @@ jobs:
     uses: ./.github/workflows/update-citations.yaml
     with:
       open-pr: true
-
-  build-preview:
-    needs: update-citations
-    if: needs.update-citations.outputs.changed == 'true'
-    uses: ./.github/workflows/build-preview.yaml

.github/workflows/update-citations.yaml

@@ -28,35 +28,40 @@ jobs:
     timeout-minutes: 15
 
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Checkout branch contents
+        if: github.event.action != 'closed'
         uses: actions/checkout@v4
         with:
           repository: ${{ github.event.pull_request.head.repo.full_name }}
           ref: ${{ github.head_ref }}
 
       - name: Setup Python
+        if: github.event.action != 'closed'
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
           cache: "pip"
           cache-dependency-path: "**/requirements.txt"
 
       - name: Install Python packages
+        if: github.event.action != 'closed'
         run: |
           python -m pip install --upgrade --requirement ./_cite/requirements.txt
 
-      # for debugging
-      - if: runner.debug == '1'
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       - name: Build updated citations
+        if: github.event.action != 'closed'
         run: python _cite/cite.py
         timeout-minutes: 15
 
       - name: Check if citations changed
+        if: github.event.action != 'closed'
         id: changed
         uses: tj-actions/verify-changed-files@v18
         with:
@@ -65,6 +70,7 @@ jobs:
 
       - name: Commit updated citations to branch
         if: |
+          github.event.action != 'closed' &&
           steps.changed.outputs.files_changed == 'true' &&
           inputs.open-pr != true
         uses: stefanzweifel/git-auto-commit-action@v5
@@ -73,12 +79,15 @@ jobs:
 
       - name: Open pull request with updated citations
         if: |
+          github.event.action != 'closed' &&
           steps.changed.outputs.files_changed == 'true' &&
           inputs.open-pr == true
         uses: peter-evans/create-pull-request@v6
         with:
           branch: citation-update
           title: Periodic citation update
+          body: |
+            To see a live preview of this PR, close (don't merge) and reopen it.
 
     outputs:
-      changed: ${{ steps.changed.outputs.files_changed }}
+      changed: ${{ steps.changed.outputs.files_changed || false }}

.github/workflows/update-url.yaml

@@ -19,8 +19,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Get Pages url
         id: pages
@@ -29,8 +29,8 @@ jobs:
       - name: Checkout branch contents
         uses: actions/checkout@v4
 
-      # for debugging
-      - if: runner.debug == '1'
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       # update link to site in readme

.github/workflows/versioning.yaml

@@ -20,8 +20,8 @@ jobs:
       github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
       - if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
@@ -85,17 +85,17 @@ jobs:
       github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
-      # for debugging
-      - uses: crazy-max/ghaction-dump-context@v2
+      - name: Debug dump
+        uses: crazy-max/ghaction-dump-context@v2
 
       - name: Checkout branch contents
         uses: actions/checkout@v4
 
       - name: Install packages
         run: npm install yaml semver
 
-      # for debugging
-      - if: runner.debug == '1'
+      - name: SSH debug
+        if: runner.debug == '1'
         uses: mxschmitt/action-tmate@v3
 
       - name: Get version and body

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Reference: common-changelog.org
 
+## 1.3.0 - 2024-08-16
+
+### Changed
+
+- List component `filters` parameter changed to `filter` and now takes any Ruby expression instead of the existing custom syntax.
+  Example: `filters="publisher: bioRxiv, date: ^2020"` becomes `filter="publisher == 'bioRxiv' and date =~ /^2020/"`.
+  See docs for more info.
+- Fix rare bug where data (e.g. a paper title) containing certain characters (e.g. a double quote) can mess up HTML rendering.
+- Fix "first time setup" workflow bug.
+- Tweak GitHub Actions debugging/logging.
+
+### Added
+
+- Styling for `<details>` HTML element.
+
 ## 1.2.2 - 2024-06-05
 
 ### Added
@@ -37,7 +52,7 @@ Reference: common-changelog.org
 
 - Add `image` param to support blog post thumbnails.
 - Add `html-proofer` plugin that checks for broken images/links/etc.
-- Add `remove` flag to remove a source from a metasource. 
+- Add `remove` flag to remove a source from a metasource.
 
 ## 1.1.6 - 2023-10-06
 

CITATION.cff

@@ -1,8 +1,8 @@
 # citation metadata for the template itself
 
 title: "Lab Website Template"
-version: 1.2.2
-date-released: 2024-06-05
+version: 1.3.0
+date-released: 2024-08-16
 url: "https://github.com/greenelab/lab-website-template"
 authors:
   - family-names: "Rubinetti"

_includes/button.html

@@ -7,13 +7,13 @@
       class="button"
       href="{{ button.link | replace: "$LINK", button.link | relative_url }}"
       {% if button.tooltip %}
-        data-tooltip="{{ button.tooltip }}"
+        data-tooltip="{{ button.tooltip | xml_escape }}"
       {% endif %}
       data-style="{{ include.style }}"
       {% if include.flip %}
         data-flip
       {% endif %}
-      aria-label="{{ button.tooltip | default: button.icon | default: "button" }}"
+      aria-label="{{ button.tooltip | default: button.icon | default: "button" | xml_escape }}"
     >
       {% include icon.html icon=button.icon %}
       {% if button.text and button.text != "" %}

_includes/card.html

@@ -2,14 +2,14 @@
 <div class="card" data-style="{{ include.style }}">
   <a
     {% if include.link %}
-      href="{{ include.link | relative_url }}"
+      href="{{ include.link | relative_url | xml_escape }}"
     {% endif %}
-    aria-label="{{ include.title | default: "card link" }}"
+    aria-label="{{ include.title | default: "card link" | xml_escape }}"
     class="card-image"
   >
     <img
-      src="{{ include.image | relative_url }}"
-      alt="{{ include.title | default: "card image" }}"
+      src="{{ include.image | relative_url | xml_escape }}"
+      alt="{{ include.title | default: "card image" | xml_escape }}"
       loading="lazy"
       {% include fallback.html %}
     >
@@ -19,10 +19,10 @@
     {% if include.title %}
       <a
         {% if include.link %}
-          href="{{ include.link | relative_url }}"
+          href="{{ include.link | relative_url | xml_escape }}"
         {% endif %}
         {% if include.tooltip %}
-          data-tooltip="{{ include.tooltip }}"
+          data-tooltip="{{ include.tooltip | xml_escape }}"
         {% endif %}
         class="card-title"
       >

_includes/citation.html

@@ -13,14 +13,14 @@
     {% if include.style == "rich" %}
       <a
         {% if citation.link %}
-          href="{{ citation.link | relative_url }}"
+          href="{{ citation.link | relative_url | xml_escape }}"
         {% endif %}
         class="citation-image"
-        aria-label="{{ citation.title | default: "citation link" }}"
+        aria-label="{{ citation.title | default: "citation link" | xml_escape }}"
       >
         <img
-          src="{{ citation.image | relative_url }}"
-          alt="{{ citation.title | default: "citation image" }}"
+          src="{{ citation.image | relative_url | xml_escape }}"
+          alt="{{ citation.title | default: "citation image" | xml_escape }}"
           loading="lazy"
           {% include fallback.html %}
         >
@@ -33,7 +33,7 @@
 
       <a
         {% if citation.link %}
-          href="{{ citation.link | relative_url }}"
+          href="{{ citation.link | relative_url | xml_escape }}"
         {% endif %}
         class="citation-title"
       >
@@ -43,7 +43,7 @@
       <div
         class="citation-authors"
         {% if citation.authors.size > 10 %}
-          data-tooltip="{{ citation.authors | join: ", " }} "
+          data-tooltip="{{ citation.authors | join: ", " | xml_escape }}"
         {% endif %}
         tabindex="0"
       >

_includes/content.html

@@ -11,7 +11,7 @@
 
 {% for section in sections %}
   {% assign dark = section | regex_scan: "dark: (.*);" | default: "" %}
-  {% assign background = section
+  {% assign image = section
     | regex_scan: "background: (.*);"
     | default: nil
   %}
@@ -24,7 +24,7 @@
       data-dark="{{ dark }}"
     {% endif %}
     {% if background %}
-      style="--image: url('{{ background | relative_url }}')"
+      style="--image: url('{{ image | relative_url | xml_escape }}')"
     {% endif %}
   >
     {{ section }}

_includes/feature.html

@@ -6,15 +6,15 @@
 >
   <a
     {% if include.link %}
-      href="{{ include.link | relative_url }}" 
+      href="{{ include.link | relative_url | xml_escape }}"
     {% endif %}
     class="feature-image"
-    aria-label="{{ include.title | default: "feature link" }}"
+    aria-label="{{ include.title | default: "feature link" | xml_escape }}"
   >
     <img
-      src="{{ include.image | relative_url }}"
+      src="{{ include.image | relative_url | xml_escape }}"
       loading="lazy"
-      alt="{{ include.title | default: "feature image" }}"
+      alt="{{ include.title | default: "feature image" | xml_escape }}"
       {% include fallback.html %}
     >
   </a>