About

Source of the website of the Canepa Research Group, caneparesearch.org. The site is built with Jekyll and published through GitHub Pages from the separate repository caneparesearch/caneparesearch.github.io.

Build the site locally

The repository is private: ask Prof. Canepa for access, then clone it and install the dependencies (Ruby 3 and Bundler; the Jekyll version is pinned in the Gemfile):

git clone [email protected]:caneparesearch/source-care-website.git
cd source-care-website
bundle install

Build the site into _site/ with bundle exec jekyll build, or preview it with bundle exec jekyll serve and open http://127.0.0.1:4000/.

A local preview runs in Jekyll’s default “development” environment, which leaves out the upgrade-insecure-requests Content-Security-Policy directive that the real, always-HTTPS site sends (update.sh builds with JEKYLL_ENV=production to turn it back on). If a local preview omits it, that is expected, not a bug — sending it locally would make the browser retry every link over HTTPS against a plain-HTTP server and fail.

Publish

publish.sh commits, pushes and publishes in one step:

./publish.sh "short description of the change" [new-file ...]

It commits the changes to tracked files (brand-new files are only included if you name them, and .jekyll-cache/ never is), pushes the current branch, then runs update.sh with the same message. Add -n for a dry run that shows what it would do, or -y to skip the confirmation. It stops before committing if the remote has commits you do not have.

To publish without committing anything, run update.sh yourself. It needs caneparesearch.github.io checked out next to this repository, the aws CLI with access to the carepapers bucket, and jq:

./update.sh "short description of the change"

It pulls this repository, regenerates the sitemap of the papers in the bucket (update_aws_sitemap.sh), builds the site, dates every URL in sitemap.xml by its last real edit in git (_scripts/generate-sitemap.rb; the plugin only knows the post date or the build date, and commits that touch more than 30 files are ignored as repo-wide sweeps), copies _site/ into caneparesearch.github.io, then commits and pushes there. It does not push this repository, so push your commits separately. It copies files over and never deletes, so remove a page from caneparesearch.github.io by hand if it should disappear from the site.

Content

Every page is a Markdown file with a short YAML header. The date at the start of a post’s file name is its post date.

Photos and figures live in images/, in a folder named after the section.

Every page gets a <meta name="description"> for search results: the page’s own description field if it has one, otherwise a post’s first paragraph, otherwise the site tagline in _config.yml, cut to 160 characters. The home page sets its own in index.html; add a description to any other page whose first paragraph makes a poor summary.

Papers

Name a paper and its files <date>-<first-author>-<journal>-<year>, all lowercase, where the journal is the ISO 4 abbreviation with hyphens, for example 2025-01-30-park-nat-mater-2025.md. If the same first author has two papers in the same journal and year, add a and b after the year. The address of a paper is built from this name, so it must be unique.

• The image is images/papers/<name>.png, referred to in the image field.
• The PDF is stored in the carepapers S3 bucket as <year>/<name>.pdf and is public. Set pdf: <year>/<name>.pdf; the site builds the download link from it.
• The doi field of a preprint on arXiv (10.48550/arXiv.…) shows the arXiv icon and the label “arXiv”, and one on ChemRxiv (10.26434/chemrxiv.…) a flask icon and the label “ChemRxiv” (Academicons has no ChemRxiv logo), instead of the DOI icon.
• The line under a paper’s title is made from authors and journal. Write authors as Surname I. I., comma-separated, with “and” before the last one (also after a comma when there are three or more) and your own name in <b>: Xie W., Deng Z., and <b>Canepa P.</b>. Write journal in ISO 4 abbreviations as Journal volume, pages (year) (no comma after the journal name), with the journal name in <i> and an en dash in page ranges and no issue number: <i>Chem. Mater.</i> 33, 5652–5667 (2021). Use Journal (year) while volume and pages are not known, and arXiv (year) or ChemRxiv (year) for preprints. The short reference in the lists on the home and Papers pages (First A. et al., <i>Journal</i>) is built from the same two fields by _includes/paper-ref.html, so the old ref field is no longer used. When the line under the title would wrap onto a second line, js/citation-fit.js shortens the authors to the first ones that fit plus “et al.”, always keeping Canepa P.; the full list stays in the tooltip.
• If you rename a paper, list its old address under redirect_from: in the header (for example - /papers/old-name/) so old links keep working. _plugins/redirect-from.rb writes the redirects.

Team

Name a team post and its image <date>-<name>, all lowercase, matching the person’s title, for example 2020-10-25-aaron-tieu.md and images/team/2020-10-25-aaron-tieu.jpg. The address of a member’s page is built from this name, so it must be unique; sidebar links (E-mail, GitHub, Google Scholar, ORCiD, etc.) are shown alphabetically by label regardless of the order fields appear in the header.

Write a bio in the first person. When a member leaves, set alumni: true, open the bio with a line saying where they are now (“I am now a research scientist at …”), and put finished student or postdoc periods in the past tense; hobbies and current interests stay in the present. On the Team page, current members are listed in reverse chronological order (most recently added first) and alumni alphabetically by name.

If you rename a team page, list its old address under redirect_from: as for papers above — except when the old and new names differ only by letter case (for example fixing capitalization), since that can’t reliably redirect on a case-insensitive filesystem such as macOS’s default disk; leave redirect_from: out in that case.

E-mail addresses

Never write an e-mail address in a page. Use the include instead, which prints “name [at] example.org” and lets js/email-links.js build the mailto link only while a visitor hovers, focuses or taps it, so the address is not in the page source or in the page as loaded:

{% include email-link.html address="[email protected]" %}

The member layout does this for the email field of a team page.

Design

• Colours are CSS variables defined in css/theme.scss. The site follows the visitor’s light or dark setting, and the moon/sun button in the navigation bar switches and remembers the choice.
• All text meets WCAG AA contrast (4.5:1) in both themes. Keep it that way when you change a colour; the navigation bar’s hover and active text uses $link-color-navlink-on-dark in css/variables.scss for this reason. Links in running text are not underlined, since their colour already sets them apart; the exceptions are links drawn in the same colour as the surrounding text (the intro sentence on the home page, the author and DOI links in .smallnote, and the footer credits), which get a faint underline so they are not told apart by colour alone (WCAG 1.4.1). Keep that underline on any new link of this kind. Every page’s content sits in a <main> element, and icon-only links carry an aria-label (with aria-hidden="true" on the icon) so screen readers can name them.
• Supported browsers are current Chrome, Edge, Firefox, Safari and Opera. Internet Explorer is not supported (the theme relies on CSS custom properties, and Bootstrap 5 dropped it).
• Photos and figures rendered through _includes/responsive-image.html (paper graphical abstracts, research/news pictures, team photos) are served as WebP with the original PNG/JPEG kept as a <picture> fallback for the rare browser or tool that cannot decode WebP; source images are never deleted, only the smaller WebP copy is added alongside. A handful of oversized news photos also get a 640px-wide WebP variant for phones, listed in _data/responsive_images.yml. Every image currently referenced this way has a WebP sibling; add one (cwebp original.png -o original.webp) whenever you add a new photo of this kind. _data/image_sizes.yml separately records each image’s pixel width/height so the include can set width/height and avoid a layout shift while it loads; regenerate an entry with sips -g pixelWidth -g pixelHeight path/to/image. Thumbnails on the listing pages (news, research, papers, team) pass loading="lazy" to the include, so browsers only fetch them once they scroll into view.
• The news archive grid and papers listing cap each card’s title to a fixed height and fade a title that runs longer than that instead of stretching the grid row (.archive-card, .paper-card-text, both built on the fade-box mixin in css/style.scss, the same idiom the homepage’s .feedbox/.feedboxblog already used).
• A floating “back to top” button (js/back-to-top.js, styled as .back-to-top in css/style.scss) fades in once a page is scrolled past 600px and smooth-scrolls to the top on click (instantly if the visitor has requested reduced motion). It is added once, in _layouts/default.html’s <body>, so it applies to every page automatically; there is no per-page opt-in.
• images/favicon/favicon.ico (and the copy at the repository root) is a multi-resolution icon (16/32/48/64px); if you replace the source artwork, regenerate it with all four sizes embedded; a single-resolution .ico renders blurry on high-DPI displays and in Windows shortcuts. images/favicon/browserconfig.xml (Windows tile icons) needs an explicit entry in _config.yml’s include: list to ship at all, since exclude: "*.xml" would otherwise drop it.
• The site is checked against the W3C Nu Html Checker and the W3C CSS Validator from time to time (most recently in September 2026, across one representative page per layout and the compiled stylesheet), and issues they find are fixed — the CSS validator’s remaining messages are informational only (vendor-prefixed selectors, and CSS custom properties, which it cannot evaluate statically). This is a manual check, not part of the build or CI; there is no script for it in this repository.
• Icons are Font Awesome Free 6.7.2 (fa-solid, fa-regular and fa-brands classes, for example fa-brands fa-x-twitter) and Academicons 1.9.5 (ai ai-doi), both self-hosted: the SCSS is in css/fontawesome/ and css/academicons.scss, the fonts in css/webfonts/ and css/fonts/. The one exception is the sun of the light/dark button, a hand-drawn inline SVG in _layouts/default.html, because Font Awesome’s sun looks like a cog. Font Awesome is trimmed to the icons the site uses: css/icons.scss lists them and emits only their classes, and css/webfonts/ holds fonts cut down to those glyphs (about 5 KB instead of 300 KB). To use a new icon, add its name to $fa-used-icons in css/icons.scss and run python3 _scripts/subset-fontawesome.py (needs pip install fonttools brotli); an icon that is not listed shows as a blank square. The full fonts it cuts from are in _fontawesome-webfonts/, which Jekyll does not publish. To upgrade Font Awesome, replace css/fontawesome/ with the new release’s scss/ and _fontawesome-webfonts/ with its webfonts/ (the .woff2 files), then run the script.
• The twitter field in a team page’s header holds the X handle; the links point at x.com.
• Styles are SCSS partials in css/, compiled into css/style.css. Layouts are in _layouts/ and shared snippets in _includes/.
• robots.txt lists the two sitemaps: sitemap.xml (the pages, written by jekyll-sitemap and re-dated by update.sh) and map.xml (the paper PDFs in the S3 bucket). Edit it in this repository, not in caneparesearch.github.io, whose copy is overwritten on every publish.
• The page /guide/format/ describes the metadata format in more detail.

Security

• HTTPS everywhere. The custom domain (CNAME, caneparesearch.org) is served over HTTPS by GitHub Pages, with Cloudflare in front as a CDN/cache (the cache-busting ?v= on css/style.css and the JS files in _layouts/default.html exists so a publish is never held back by a stale Cloudflare or browser cache). In production, the page’s Content-Security-Policy sends upgrade-insecure-requests, so a browser retries any accidentally plain-http:// link over HTTPS instead of loading it insecurely (see “Build the site locally” above for why a local preview leaves this out). Paper PDFs in the carepapers S3 bucket are likewise only linked over https://. Cloudflare’s own SSL/TLS mode and GitHub Pages’ “Enforce HTTPS” setting are account/dashboard configuration, not files in this repository, so they aren’t documented here beyond that they’re on.
• Content-Security-Policy and Referrer-Policy, sent as <meta> tags in _layouts/default.html: base-uri 'self' and form-action 'self' stop an injected script from changing the page’s base URL or submitting a form somewhere else; object-src 'none' blocks <object>/<embed> plugin content entirely; Referrer-Policy: strict-origin-when-cross-origin sends the full page URL as a referrer only to the same site, and just the origin (no path) to other sites.
• No e-mail address ever appears in a page. See “E-mail addresses” under Content above — email-link.html prints an obfuscated “name [at] example.org” and js/email-links.js builds the real mailto: link only once a visitor hovers, focuses or taps it.
• The members area is not an authentication system in this repository. The padlock icon in the navigation bar is an outbound link to a separate Google Sites page that itself requires a Google sign-in; this codebase has no login, sessions or credentials of its own.
• robots.txt allows every crawler (Disallow: is empty) and lists both sitemaps, so nothing on the site is meant to be hidden from search engines.

File conventions

.gitattributes and .editorconfig keep every text file in LF line endings, UTF-8 and ending with a newline, as POSIX defines a text file. Let your editor honour them, and do not save files with CRLF endings or without a final newline. The one exception is google736838dc293297e8.html, the Google Search Console verification file, which must stay exactly as Google issued it.

License

All source code in this repository, consisting of files with extensions .html, .css, .scss, .rb or .js, is freely available under an MIT license, unless otherwise noted within a file. You’re welcome to borrow / repurpose code to build your own site.

The MIT License (MIT)

Copyright (c) 2018-present Pieremanuele Canepa with the help of Bedford

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.