Configure the RenkuLab Homepage

Homepage

The homepage is shown at the root URL of a RenkuLab instance to a non-logged-in visitor. (A logged-in visitor sees the Welcome page.) By default, this page shows an explanation of the features of RenkuLab, but its content is configurable by altering the renku/values.yaml file.

Configuring the content

There are two pieces of information that most deployments will want to customize: the link to the tutorial and the list of projects to highlight on the homepage.

ui.homepage.tutorialLink

ui.homepage.tutorialLink contains the URL that is used when a user navigates to the tutorial. The default is to take the user to the tutorial in the documentation: https://renku.readthedocs.io/en/latest/tutorials/01_firststeps.html. If your deployment has a custom tutorial, for example, one hosted on the deployment itself, you can replace the link to the tutorial.

ui.homepage.showcase

A deployment may want to highlight certain projects that are hosted on it. The field ui.homepage.showcase makes that possible. To activate the showcase section on the homepage, set ui.homepage.showcase.enabled to true.

There are several configuration settings for the section header.

ui.homepage.showcase.title - The title shown for the section
ui.homepage.showcase.description - The Markdown description shown for the section

The list of projects shown in the showcase is controlled by the ui.homepage.showcase.projects field. This is a list, and each element needs to include the following required field:

identifier - The fully qualified name of the project.

By default, the title, description, and image for the showcase card are taken from the project.

If you wish to override these values, you can use the following optional fields:

overrideTitle – text for the title of the card
overrideDescription – Markdown for the description of the card
overrideImageUrl - An URL resolving to an image of any format supported by the img tag, including PNG, JPG, and SVG.

E.g.,:

showcase:
  enabled: true
  title: Showcase
  description: "A selection of **projects** hosted on this instance."
  projects:
  - identifier: renku-tutorials/e-rum-2020
  - identifier: covid-19/covid-19-forecast
    overrideTitle: "COVID Forcasting"
    overrideDescription: |
      This project contains an attempt to _forecast_ COVID-19 infection rates.
    overrideImageUrl: https://github.com/SwissDataScienceCenter/renku/blob/master/docs/_static/icons/logo.svg

Here is an example of what the showcase section could look like:

Replacing the content

If the default content is not appropriate for your deployment, it is also possible to replace what is shown on the homepage.

There are three values that control the main content on the homepage: ui.homepage.custom.enabled, ui.homepage.custom.main.contentMd, and ui.homepage.custom.main.backgroundImage.url

ui.homepage.custom.enabled

ui.homepage.custom.enabled needs to be set to true to enable overriding the homepage content. If left empty or set to something else, the customization settings will be ignored and the standard RenkuLab homepage will be shown.

ui.homepage.custom.main.contentMd

This variable stores the text that will be shown. Content should be provided in Markdown syntax. If ui.homepage.custom.enabled == true, but ui.homepage.custom.main.contentMd is empty, then dummy content is shown indicating that something should be provided here.

ui.homepage.custom.main.backgroundImage.url

By default, the text is presented over a standard background image. If you wish to provide a different background, you may do so by setting this variable to the URL for the background you want to show. Any format supported by the background-image property in CSS is allowed, including PNG, JPG, and SVG.

Note

The background color for the surrounding content is #01192D, rgb(1, 25, 45). To achieve a seamless look, you should probably should use this color in at least border of your image.

Note

A convenient place to store an image you want to use would be in a Git repository hosted in the GitLab used by RenkuLab. The repo can be a plain Git repo (it does not need to be a Renku repo).