tl;dr

Copy one of the message files in content/important_messages/ and change the publishDate, expiryDate, startDate, title and importance values. Also change the content to the message you want to appear!

If you want a red box, give an importance value of 100 or more. If you want a grey box, give an importance value of between 0 and 99. If there is more than one message box, the order is from highest importance value to lowest.

Creating important messages

To set an important message (a message that appears at the top of every page, below the title and navbar but above the content):

1. (this step might already have happened) Create content/important_messages/ with the following file as _index.md (THIS IS IMPORTANT in order to prevent publication of the messages as separate pages (which wouldn’t be a disaster as they’re not linked to)). The body part will not be published anywhere.

---
headless: true
cascade:
- build:
    list: local
    publishResources: false
    render: never
title: Important Messages
display: none
---
This _index.md should not be published.

2. Create a .md file for your message in content/important_messages. The filename does not matter, but preceding it with an ISO-8601 YYYY-MM-DD for the publish date keeps things in order in the filesystem (it doesn’t affect the order of the messages).

Message format

The file should include hugo frontmatter as follows:

• publishDate (mandatory) Sets a date time for hugo publication on the website. This determines whether the message goes into the HTML.
• startDate (optional) Sets a date time for visibility on the website – this is controlled by some javascript in the important_messages.html partial output since the webpage is static and you may want to publish the website before the message is due to appear.
• expiryDate (mandatory) Sets a date time for expiry on the website. This is controlled both by some javascript in the partial output and whether hugo publishes the message in the HTML in the first place. This is because you will probably not publish a new website exactly when the message is due to expire.
• title (optional) will appear as a bold title.
• importance (mandatory) determines the order the messages appear, with higher importance appearing first. This wil also set a default colour scheme (see below).
• colour_scheme (optional) overrides the colour scheme set by importance, and can be red, grey or none.
  • To add more important message box colour schemes see themes/jalview/assers/css/important_message.css.
  • To change default colour schemes for importance levels see themes/jalview/layout/partials/important_messages.css.
• display (optional) Set this to none to ensure a message does not get published.

Colour schemes and overriding CSS

The expected scenario is that you just set an importance value and let the important_messages.html partial decide what to do with colouring. However, there are built-in easy ways to defeat this.

Default colour schemes

If no colour scheme or CSS is set then a colour scheme is added depending on the importance level (which is mandatory.

• importance ≥ 100 → "red" a dark red box with black border and white text with a lighter link colour
  
  
• importance ≥ 0 and importance < 100 → "grey" a light grey box with green border and black text (as used in the exercises for manual links)
  
  
• importance < 0 → "none" no colouring or border. Use this with the below if required.

Overriding CSS

The following optional parameters will override specific parts of the CSS in the chosen colour scheme. If you want to start from scratch then also set colour_scheme: none. These settings are added as a <style> element within the important_messages <section> and !important is automatically applied to all specified values.

• background_color (optional) The background colour of the box. All CSS color values can be used.
• color (optional) The foreground (text) colour for the whole box. All CSS color values can be used.
• border (optional) The border CSS specification for the box (border-radius is always set), e.g. 2px solid black
• title_color (optional) The foreground (text) colour for just the title. If not given then color will apply. All CSS color values can be used.
• link_color (optional) The :visited and non-:visited color for links. Set this if the standard link colours do not contrast with the background_color. All CSS color values can be used.
• link_hover_color (optional) The :hover color for links. Set this if the standard link colours do not contrast with the background_color. All CSS color values can be used.

Adding colour schemes

The colour scheme value is implemented as an extra class name to the outer <div class="important_message_box">. CSS set in themes/jalview/assets/css/important_message.css controls the appearance of different colour scheme values, except for colour_scheme: none which doesn’t add an extra class. To create a new colour scheme simply add an extra CSS block to important_message.css, e.g.

.important_message_box.green {
  background-color: lime;
  color: black;
  border: 2px dashed #090;
}

and set

colour_scheme: green

in the message frontmatter.

To add new colour schemes as defaults in the importance range you will need to edit the code in themes/jalview/layouts/partials/important_messages.html at around line 92:

    {{- if lt $params.importance 0 -}}
    {{- else if lt $params.importance 100 -}}
      {{- $colour_scheme = "grey" -}}
    {{- else if ge $params.importance 100 -}}
      {{- $colour_scheme = "red" -}}
    {{- end -}}

Content

The message content should be in markdown and can include shortcodes like the markdown rendering of any other page content.

Example message file

(filename: content/important_messages/2024-03-21-scheduled_downtime.md)

---
publishDate: 2024-03-21T09:00:00+01:00
startDate: 2024-03-21T12:00:00+01:00
expiryDate: 2024-04-05T18:00:00+01:00
title: "Jalview's Web Services: Scheduled Downtime 1st-5th April"
importance: 110
---
Jalview's alignment and other web services will be unavailable for up to 4 days from 5pm BST (UTC+1) on Monday 1st April 2024.
For more information see the [announcement on the Jalview Discussion Forum](https://discourse.jalview.org/t/jalviews-services-unavailable-for-4-days-from-17-00-bst-utc-1-on-monday-1-april/2107).

which should render as

Message ordering

The order of messages is by most important to least, based on the importance value given, across all messages found for that page.

If you want a message to appear above a red message but not be red then override the colour_scheme.

Sectional important messages

If you want some messages to appear in individual sections, you can create a content/section/important_messages/ folder with an _index.md the same as given above, and then add message .md files the same. These messages will appear on every page in that section.

Exempt pages

If you have an individual page that should not show messages, you can add a frontmatter parameter to that page:

important_messages: none

which will mean no messages are published on that page.