Metadata information in How-to Cards#

All cards have a “YAML header” that may contain interesting metadata that are processed in special ways. A typical YAML header may look as this:

---
mount: contribute/metadata
name: "A card about metadata"
tags:
  - contribute/basic
  - integrity

revised:
  by: Mirek Kratochvil
  date: 2025-10-07
---

# Metadata information in How-to Cards

... card text continues here

Notably, YAML is a standardized data exchange format that is quite easily convertible to JSON, and thus can be easily processed with automated tools. YAML official website collects useful resources for learning about possible details.

Here, we list and interpret all useful metadata items.

Basic information#

Card placement#

mount#

The local part of the URL where the card “appears” to sit in the browser. For example, a card that specifies:

mount: general/something

…will be available at URL https://howto.lcsb.uni.lu/general/something.

name#

The human-readable name of the card that is used to show references that point to the card. Mainly, this name will be displayed in the category listings, and in the title bars of the browsers.

Example:

name: "A card about something"

(The quoting is not mandatory but it is useful to prevent special characters from being interpreted by YAML. Typically, a name that contains a colon (:) must be quoted, so that it is not interpreted as a YAML dictionary.)

redirects#

An array of mounts that should be redirected towards this card. For example, specifying:

mount: new/card

redirects:
  - old/page

…will cause everyone who tries to open a link to https://howto.lcsb.uni.lu/old/page to be automatically redirected to https://howto.lcsb.uni.lu/new/card.

This is primarily used to make sure that links to cards that have been moved elsewhere will still work.

Categorization via tags#

Each card may belong to multiple “categories”, called tags. The membership of cards in tags generates the lists of cards and the category structure.

The tags in How-to cards are categorical – you may use slash to separate the tag name into “directories”, and the card is then visible in the whole directory hierarchy. This allows us to specify very precise card categorizations (e.g., a card may be categorized into integrity/research/grants) while also allowing people to easily see all cards that belong to broader categories (e.g., listing a category integrity will also show the more specific card that belongs to integrity/research/grants).

For example, a card that belongs to the contribution guide but also talks about backups may be categorized as follows:

tags:
  - contribute/basic
  - integrity/backup

The implementation of hierarchical tagging essentially places the card into all “parent” categories; thus card tagged with category a/b/c will also belong to a/b, a, and the special “root” empty-named category of all tagged cards `. In turn, if a card is already placed in categorya/b, it is not necessary to explicitly place it intoa`.

The category names should be preferably concise and machine-readable, as they appear in the listing URLs. If you need a nice name for the category, you can specify one in files called tag-metadata.yml. The files are formatted as follows:

# file "tag-metadata.yml"

/: "All cards"
contribute: "Contribution process"
contribute/basic: "Contribution basics"
integrity/backup: "Backup guidelines"

ordering the cards in listings#

To be able to specify a custom ordering of the cards in category listings, you may specify the order explicitly. The order may be a number or a string; by default the order is assumed from the card name, if the name is not present it is taken from mount.

The cards in category listings are then sorted in this order:

• cards with negative numeric order come first, based on the negative number value (-5, -4, -3, …)
• card with order: 0
• all cards with string order, sorted by version sort (this includes all cards with unspecified order, sorted typically by the name)
• cards with positive numeric order come last, based on the number value (1, 2, 3, …).

E.g., to place the card on the top of the category, you use:

order: -1

To make the card “sort nicely”, ignoring language issues, you can specify:

name: The Alphabetic Tutorial
order: Alphabetic Tutorial

(…the card will be sorted together with cards that start with A, as opposed to the cards starting with T)

Optional features#

search#

All cards are processed to be available via the built-in full-text search by default. To disable inclusion in the search, use:

search: off

Tables of contents (tocs)#

By default, all cards get a short table of contents (ToC) displayed in the info box, which lists all headers up to the level 3.

You can turn the ToC off by:

toc: off

If you want to reduce or increase the amount of headings displayed in the ToC, you may specify it with the number. E.g., this is going to display all headings up to the ones starting with 4 sharps (####):

toc: 4

Metadata specific for How-to Cards#

revised#

Revision information may be added via revised tag. The revision information is simply collected and displayed in the huge revision table. Maintainers use the information to detect possible outdated cards.

Whenever reviewing or updating a card, you should add or update the revision note:

revised:
  by: Your Name
  date: yyyy-mm-dd

…where instead of the yyyy-mm-dd you use the current date, such as 2025-12-31.

QMS integration#

Inclusion of QMS-related information triggers display of the QMS “shield” marks, mandatory-warning banners, and links the cards very visibly to the approved documents.

sops#

You can specify a list of standard operating procedures that the card refers to:

sops:
  - qms/LCSB-SOP-ADM-001
  - qms/LCSB-SOP-ADM-002

(The qms/ prefix is mandatory, partially for simplification (it is the same as the link format), and partially for the situation when SOPs might come from other sources than QMS.)

policies#

Just like with SOPs, you can link to policies:

policies:
  - qms/LCSB-POL-DAT-001

The processing is identical to sops, except for minor details in rendering.

qms_notice#

For some (mandatory) How-to Cards, it is useful to display a warning banner that clarifies that the elaborated procedures/rules must be followed. The banner is displayed if at least one of either of the sops and policies are specified, and the banner is additionally enabled explicitly via:

qms_notice: on