greenelab / lab-website-template

An easy-to-use, flexible website template for labs.

Lab Website Template

Lab Website Template (LWT) is an easy-to-use, flexible website template for labs. Spend less time worrying about managing a website and citations, and more time running your lab.

👇👇 Get Started 👇👇

Documentation

Key Features

• 🤖 Based on Git, GitHub, and Jekyll.
• 📜 Automatically generated citations from simple identifiers (DOI, PubMed, ORCID, and many more) using Manubot. E.g. doi:1234/5678 -> title, authors, publisher, date, etc.
• 🧱 A comprehensive and flexible suite of pre-made components (building blocks) for structuring and styling your website:
  • Formatted tables, code blocks, figures, and other basic elements.
  • Citations with thumbnails and other rich details.
  • List large sets of data with flexible filters and components.
  • ...many more
• 👁️ Automatic pull request previews.
• ⚙️ Easy and automated configuration.
• 👥 Team member pages with bios, roles, and social media links.
• 🖋️ Blog posts with tags and rich content.
• 📱 Works and looks good on desktop and mobile.
• 🤝 Great documentation and support (if we do say so ourselves).
• ... and much more!

lab-website-template's Issues

Multi-language support

If you want this feature, please 👍 this comment so we know how much demand there is.

This would add complexity to the template, and I feel that Google Translate and other browser extensions fill this gap decently well.

Feature component fixes

• Full-sized image
• Title vs. heading parameter
• Accent-colored heading

Make testbed

Make thorough testbed file for testing components.

Make sure there are fallbacks for all parameters, including providing empty lists. Make sure components work in all orders, on all screen sizes, etc

Add note about prepopulating card search input

Tell users somewhere that they can append ?search=some search terms to the url to prepopulate the card search component's input field.

Auto-cite plugins for NCBI and Google Scholar

Add ORCID to social link component

template button not generating

No option to create a new repository from template, just to clone the repository

Image storage

Enumerate social link, role, and paper link types in data?

I used to have it this way, but then moved it to hard-coding it in the include files themselves.

But due to the TISLab migration, I'm thinking it will be more common than I thought to add custom types, and we should go back to abstracting these types out into yaml, which will be easier for users to understand and edit. The only downside is that it clutters the _data folder with more things the user may not need/want to edit.

I think this again a case of bias towards the way we did it for greenelab.com, where we had very nice/neat categories like undergrad/grad/pi/programmer/etc. But in TISLab, they have more specific titles that should be displayed, like "Bioinformaticist" and "Ontologist" (in fact everyone seems to have a unique title).

Allow spaces in tags

Force tag parameter to be array (currently it accepts a string).

Markdownify in card component causing issues with specific Manubot citations

I was looking through the list of conferences the lab publishes in and caught that one of the many, many publications is rendering a little weird. I thought I'd share in case it's helpful to know about! (This is in Safari on an iPhone if you can't tell from the screenshot, just in case it doesn't happen in other platforms!)

ETA: Also on a mac in FireFox

Indent liquid for code readability

Add "tips" section to docs?

With some very basic/generic tips on how to make your website look better? Eg. "use background images that are not too busy and distracting", or "use a square, transparent version of your logo with good contrast on the background"

Make flat default

Get rid of the default shadow and zoom-on-hover effect on images. Thinking about it months later, I think it looks no-good and people probably don't want it. At the least, it doesn't need to be a parameter in all the image components.

Perhaps get rid of the entire option to have a shadow. Or maybe just comment it out in the css.

Add single citation component?

We have a research list component, where it lists all research on the site. But it's easy to imagine a user may want to put a citation to a single paper in the middle of a page, say in the middle of a blog post.

Incorporate supported plugins

There are a bunch of plugins that github pages supports, and some of them might be useful.

Namely, the sitemap plugin may be a way to get rid of the nav parameter in config.yaml that I have not yet taken advantage of. This plugin didn't do what I thought it did, but found a way to accomplish the goal anyway.

Make header/footer none work for site-wide (in config.yaml)

Add RSS feed

I think it would be nice to have an RSS feed for the site. It could cover the blog, research and resources.

Update template based on new wiki documentation

• /icons -> /favicons
• heading -> title in feature component
• type -> group in resource-list component and resources.yml
• remove order in team-list component (until someone requests this)
• remove placeholder parameter from includes
• delete /_data/team-order.yml
• add quote block styles
• delete comments in /_data/research-input.yml, /_data/resources.yml, /_includes/header.html
• delete/reduce images
• reduce readme to barebones, and refer to wiki for documentation

Research paper search not hiding papers

This is a regression bug. Judging by the "# of # papers shown" text, it's filtering them properly. It's just not hiding the actual paper DOM elements.

Advanced instructions: How to inline SVGs

Took this out of the documentation, because almost no one is going to want to do this.

---

You can put SVGs you wish to inline in the /_includes folder.

Inlining an SVG means putting its source code directly into the page, instead of linking to it as a separate file using an <img> tag. This allows you to style an SVG (things like fill color, stroke width, etc) from outside of it. This way you can use the same image in multiple different contexts without duplicating it. For example, you can have a single logo file, and color it white when on a dark background, and color it black when on a light background.

Try using currentColor in your SVG to have it always match the color of text it appears next to. Or if you're more advanced, you can style your SVG with separate CSS where needed.

Inlining an SVG also allows contents outside of its bounding viewbox to be shown on the page.

Confusing publication sort order

I expected publications to be sorted in a date order with the most recent first, but I'm not able to easily see how that sort is happening.

Blog HTML tweaks

• in blog post layout, wrap nav in <section>
• in blog-list component, remove first <hr>

Table of contents plugin

Would be nice to have a table of contents for longer pages of content. This can be done pretty easily with javascript like we did for Manubot, but it'd also be nice to have it statically generated at compile time. Unfortunately github pages doesn't support jekyll-toc, so it'll have to be done with javascript for now.

Advanced instructions: Previewing and building the site and citations locally

Added to wiki documentation.

See this comment's edit history for older instructions.

Add text option to social link component?

Per this comment, maybe social links on team member bio page would be easier to read/recognize if they had text in addition to the icon?

This would work with a text boolean option, like the role component has, and would be set to true for _layouts/member.html and left false elsewhere (eg, don't want the text next to the icons in the footer).

Simplify documentation regarding master/main/branches/forks

Based confusion in this PR: greenelab/greenelab.com#32

It's tough to write docs because there are many different ways you can make and preview changes... on your computer, through github, directly to main, from a branch, from a fork, etc.

It's also just too much to read through for someone just wanting to jump in and make a change quickly.

Need to figure out a way to make the Getting Started docs page clearer and automatic citations build section clearer.

Documentation feedback

Comments from @ben-heil in our Slack, wanted to put them here for posterity and also to discuss.

1. The "Getting Started" button should either be first or right below the home button (and maybe also mentioned in a sentence on the homepage of the wiki)
2. "Felix Cited" is the best name for a fake researcher
3. You may want to make "Component demos" into a page on the Lab Template site itself so that you can show what the components do
4. In Basic-editing/folders it's a little unclear what a sub-folder for a site means. Maybe use "Any sub-folder you create in your repo will create a page on the resulting site".
5. It probably would be a pain to make, but having a series of images of the template site with the area where each element in the config file shows up would be helpful here: https://github.com/greenelab/lab-website-template/wiki/Basic-Editing#config-file
6. "Customization" could also be called "Advanced editing" since it's not something most people will need

Merge social link, big link, and paper link into single component type

There's a lot of overlap between these components. They all have a font awesome icon, some text, and a link to a url. This is an opportunity for simplification

Add tags option in research, resource, and blog list components

Team list and resource list components can show items based on an arbitrary group parameter.

I plan to add the functionality to filter (dynamically, with javascript) cards and other items on a page based on their tags, but perhaps a website maintainer may want to list items in a particular order based on their tags.

For example, for team members, you can do:

{% include team-list.html group="current" %}
{% include team-list.html group="alum" %}

Maybe it would be useful to allow:

{% include blog-list.html tags="cancer, covid" %}
{% include blog-list.html tags="biology" %}

Add LinkedIn (and others)?

Add LinkedIn and possibly other platforms to built-in social links? Do people still use LinkedIn?

Make terminology/names more consistent

research, papers, citations, publications, entries, input, output, team, members, blog, posts

Lots of conflicting and overlapping terminology. Need to make them consistent and clearer, most likely involving renaming a bunch of things in the code.

Add PR template with link to template docs

To warn people to check the template docs BEFORE even opening the PR for less problems.

Also future me, don't forget to put this in Greenelab.com repo as well.

Add flat option for figures

Add "flat" option for figures like the gallery component has.

Make build-research.py more robust

Currently build-research.py can be a little fragile in certain edge cases, like when research-output.yml exists but is empty or not in the expected format.

We should add more checks to make sure the yaml is valid, and also the shape of it is valid. And we should add more clear error messages.

Perhaps at the end of running the script, we should also list which DOI's (or etc) couldn't be found or cited.

Unable to add new tabs in the website

I was trying to add more tabs to the lab website. But I am not sure how to add it. I tried making a folder and then added a .md file with some contents, but on pushing it on GitHub, no new tab was created. Please help me out with this.

Site wide search?

It may be possible to add an instant site-wide search component using Lunr. This would be a good feature to have if it's easy to implement, ie there is a third party library/plugin to do the heavy-lifting.

Make research and resources less opinionated?

We have a team list component that shows all the team members in /_members with their picture, name, and role. That, I feel, is going to be pretty standard across the board; what everyone will want.

But while migrating the TISLab to the template, I've realized the template is biased toward the way greenelab.com organizes and separates its information between the "Research" and "Resources" page. Those two things can very much be interwoven and overlapping.

For example, one project might have several papers to show citations for, a big image, a hand-written description, and social media links to github/twitter/etc. This is sort of how this TISLab page is at the moment.

Perhaps there is a more generic way to set up the template so that users can easily set up lists of content, whatever those lists may be.

Support forks after all?

Templates are good because you can get a copy of the repo without all of the commit history. If you're starting a new website for your lab, you don't care about the commit history of the template itself; you care about your own commit history.

However, if you need to pull updates from the template, it's a huge PITA because you have to manually resolve merge conflicts. Also, you end up getting a bunch of extra commits in the PR from the template anyway, like this.

Perhaps we could explain here that you can do a template or a fork, depending on what you want?

Or maybe there's some workaround where you can get easy/automatic merges, and without extra irrelevant commits...

@dhimmel (git expert) @cgreene @dongbohu do you have any thoughts about this?

Error by build-research.py

I am getting this error after following your steps on automatic citations-

"Traceback (most recent call last):
File "build-research.py", line 44, in
matches = [p for p in output_papers if p.get("id", "") == input_paper.get("id", "")]
TypeError: 'NoneType' object is not iterable"

I think there is some problem with the .yml file. Do you want me to attach that file here ?

Update documentation for automatic citations

If you're skipping testing/previewing (committing directly to master), there are still steps you have to do to set up (github actions) for automatic citations to work properly.

Header/footer fixes

• Make header/footer none work for site-wide (in config.yaml)
• Option for header/footer light background color for darker logos
• Move section dark styles to background

Option for header/footer light background color

For darker logos.

Make automatic citations work on master/main?

I added the doi numbers along with doi links in the /_data/research-input.yml and then commited those changes. After that I pushed it to main branch. However, The github was facing problem building the website. The error was "Page build failed.". Please take a look at this.

General documentation improvement

There's a lot to document here, and the readmes and comments can be a bit unruly for people who just want to set up a website quickly.

Here are my cursory thoughts on the situation.

Short term solution: Re-order sections of readme so more important things are first. Also add links where specific files and folders are called out so users follow them to more specific documentation.

Long term solution: Make a full "docs" site that is split into pages, and move all documentation there (except for under-the-hood comments on specific lines of code that users aren't meant to read).

I will have to think a while about the best way to do this, as there are many things to consider.

Generic two column layout component

Would be useful to have a component that allows arbitrary content (markdown, other components, etc) to be put into two columns (that collapse to one column on mobile"). Could be useful for side-by-side figures and much more.

Add explicit marker for section breaks

Currently, the template tries to be clever and break the page into sections (the alternating white and light-gray backgrounds that span the entire width of the page) based on where <h1>'s and <h2>'s occur. It's probably better to just have a custom, short, explicit marker, like <!-- section break --> where users can tell the template exactly where to put the sections. This would be helpful for where you might want a section break but without a header, such as the Prev/Next Post navigation links at the bottom of a post. It would also be less prone to error.

Handle case where user builds citations locally more gracefully

If a user builds citations locally, when they make a PR, github actions will also to build them, causing a conflict in the research-output file.

Handle this better. Perhaps don't let the action run if output has also been touched.

Creating clickable tags

New to this template, but it looks great. Are there any plans to make the tags clickable in order to filter the Research or Blog pages? It would then also be helpful to have list of all tags used on either page that could be clickable on the right or bottom of a page.

Additional features

Hi Vince,

Thank you for creating this template. There are several things that might be great to add to this template.

1. Blog/News page: do you think we can add tweets from lab account to this page. I think it would be awesome to have both blog posts and news/tweets from lab account twitter.

2. For each Blog post (or any page): can we add option for discussion/comments (something like Disqus)?

3. Can we add the instruction on how to add/delete a page? For examples, if a lab wants to add a page for "Tutorials", what do they need to do in order to make sure that everything will work in this new page (edit nav.html, edit _config.yml etc.).

4. Can we also add the the instruction for adding website logo and necessary favicons for different browsers/platforms?

5. I think this template will be popular. It might be great to have another version for multi-language setup.

Cheers 👍
Nat