Syntax Reference for `metadata.json` (v2)

This page documents the schema version 2 for metadata.json files in the HKU Notes project.

Schema Version

This documentation covers schema v2, the current recommended version for new build targets.

If you're working with older files, see the v1 syntax reference.

Key Naming Conventions

All keys in the metadata.json file should be in snake_case format. In this documentation, dots (.) are used to represent a hierarchy of keys. Keys should not contain dots in their names.

Example

The key build.build_command would mean:

Correct Interpretation

{
    "build": {
        "build_command": "..."
    }
}

rather than:

Incorrect Interpretation

{
    "build.build_command": "..."
}

An arbitrary object of an array is denoted using [i]. The keys of the object are enclosed within curly braces {}.

Example

The key static_site.buttons[i].{text} would mean:

{
    "static_site": {
        "buttons": [
            {
                "text": "Button 1"
            },
            {
                "text": "Button 2"
            }
        ]
    }
}

Schema Overview

Schema version 2 has only one required field: $schema. All other fields are optional. All keys and their behaviours remain unchanged as in version 1, except for those listed below.

Changes from v1 to v2

static_site.primary_button and static_site.secondary_button have been replaced with static_site.buttons, an array of button objects.
Version is now specified using the $schema field instead of @metadata_file_version.

Backward Compatibility

The build pipeline will automatically parse v1 formats and convert them to v2 internally, so existing build targets using v1 schema will continue to work without any changes.

Schema Fields

`$schema`

Required: Yes
Description: Reference to the JSON schema for validation and IDE support. Must be set to the v2 schema URL.
Type: string
Value: "https://hku.jacobshing.com/statics/schemas/v2.json"

`@metadata_file_version` [Deprecated]

Deprecated Field

The @metadata_file_version field is deprecated in v2 and replaced by the $schema field.

For backward compatibility, you may still include this field (set to "2"), but it is no longer required or recommended for new files. The build pipeline will prioritize $schema for version detection.

Required: No (deprecated)
Description: Legacy field for specifying metadata schema version. Replaced by $schema in v2.
Type: string
Value: "2" (if present)

`build.root_file`

Description: Specifies the main file to be built for the target.
Type: string
Default: [BUILD_TARGET].tex where [BUILD_TARGET] is the name of the build target.

`build.output_file`

Description: Specifies the name of the output file to be generated after building the target. The build pipeline looks for this file after executing the build command.
Type: string
Default: [BUILD_TARGET].pdf where [BUILD_TARGET] is the name of the build target.

Non-File Targets

If the build target does not produce a file (e.g., only a web page), you must create a dummy file with the name "NON_FILE_TARGET" in the source directory of the target. You must also point the build.output_file to this dummy file.

`build.no_latex`

Description: If set to true, the build pipeline will skip the LaTeX installation and proceed to the commands specified in build.prebuild_command, build.build_command, and build.postbuild_command directly. This is useful for targets that do not require LaTeX to build, such as HTML or Markdown documents.
Type: boolean
Default: false

`build.requires`

Description: A list of dependencies that are required to build the target.
Type: array of string
Accepted Values:
- python-minted-pkgs: Instructs the pipeline to install the required Python packages for the minted LaTeX package.
Default: null

`build.prebuild_command`

Description: A command to run before building the target. This command is executed in the source directory of the build target, i.e., /src/[BUILD_TARGET].
Type: string
Default: null

`build.build_command`

Description: The command to build the target. This command is executed in the source directory of the build target, i.e., /src/[BUILD_TARGET].
Type: string
Default: latexmk -pdf -f -interaction=nonstopmode -cd -outdir=. ./[ROOT_FILE] where [ROOT_FILE] is the value of build.root_file.

`build.postbuild_command`

Description: A command to run after building the target. This command is executed in the source directory of the build target, i.e., /src/[BUILD_TARGET].
Type: string
Default: null

`static_site.description`

Description: A short description of the target, used in the static site.
Type: string
Default: "-" (a hyphen)

`static_site.meta_description`

Description: A short description of the target, used in the HTML meta tags for SEO purposes. If not specified, the tag will be "Download [BUILD_TARGET] for free - [DESCRIPTION]", where [BUILD_TARGET] is the name of the build target, and [DESCRIPTION] is the value of static_site.description.
Type: string
Default: null

`static_site.custom_md_file`

Description: A custom Markdown file whose content will be copied to the end of the static site page for the target. It should use the Markdown syntax for Material MkDocs.
Type: string
Default: "" (an empty string, meaning no custom Markdown file is used)

`static_site.document_status`

Description: The status of the document, used in the static site. It must be one of the values in the Accepted Values section.
Type: string
Accepted Values: Refer to the Document Statuses for the accepted three-letter codes and their meanings.
Default: "unk" (Unknown)

`static_site.alias_to`

Description: Treats the target as an alias to another build target. This is useful when a course has more than one course code.
Type: string
Accepted Values: The name of another deployed build target.
Default: null

Alias Targets

If a build target is an alias to another target, it will not be built. Therefore, all the commands specified in the build section will be ignored. Moreover, alias targets do not get their own page on the static site. Therefore, all other keys in the static_site section will be ignored as well.

In the description field of the alias, it will display: "(Alias to [TARGET_NAME])".

See the target COMP2113-Cheatsheet on the course catalogue page for an example of an alias target.

Alias Must Point to a Deployed Target

An alias target must point to a build target that has already been deployed, otherwise the build pipeline will fail.

For example, if you would like to create a target COMP2113-Cheatsheet that points to ENGG1340-Cheatsheet. You must first add and successfully deploy the target ENGG1340-Cheatsheet before you can add the alias target COMP2113-Cheatsheet.

`static_site.pdf_viewer`

Description: Where the PDF viewer (if available) should be displayed on the details page.
Type: string
Accepted Values: Any of the following:
- "at_head": Display the PDF viewer directly after the authors and the two buttons (at the head of the custom markdown page).
- "at_footer": Display the PDF viewer after the end of the custom markdown page.
- "at_tag": Insert the PDF viewer at the  tag in the custom markdown page.
- "hidden": Do not display the PDF viewer at all.
Default: "at_head"

PDF Viewer Placement

General Reminder: The PDF viewer will be displayed if and only if the output file is a PDF. When the output file is not a PDF file, setting this key will have no effect.

When using the at_tag option: The custom markdown file must contain exactly one  tag (case-sensitive). Missing tag or duplicated tags will cause the build pipeline to fail.

`static_site.buttons`

Description: An array of button objects that define the buttons to be displayed on the static site. Each button object must conform the structure described below.
Type: array of object
Default: null

Default Value Behaviour

If the static_site.buttons key has the default value of null, the build pipeline will automatically create two buttons: a primary "Download" button and a secondary "View Source" button, with the same properties as in the v1 schema.

However, if you wish to display no buttons, you must explicitly set static_site.buttons to an empty array [].

`static_site.buttons[i].{index}`

Description: The index of the button in the array. Used to determine the order of buttons.
Type: integer
Default: 0

Default Index Undefined Behaviour

By default, all buttons have an index of 0, which means their order can be inconsistent between builds. You should explicitly set distinct indices for each button to ensure a consistent order.

`static_site.buttons[i].{is_primary}`

Description: Whether the button is a primary button or not.
Type: boolean
Default: false

Multiple Primary Buttons and Ordering

It is allowed to have multiple primary buttons.

The order of buttons is soley determined by their index values, regardless of whether they are primary or secondary. Buttons with lower index values are displayed before buttons with higher index values.

`static_site.buttons[i].{text}`

Required: Yes
Description: The text to be displayed on the button. You must explicitly set this value for each button.
Type: string

`static_site.buttons[i].{icon}`

Description: Defines the icon and href of the button.
Type: string
Default: null (no icon)
Accepted Values: Any valid icon name specified in the Material for MkDocs documentation,

`static_site.buttons[i].{href}`

Required: Yes
Description: The URL to be linked to when the button is clicked. You must explicitly set this value for each button.
Type: string

`static_site.buttons[i].{message}`

Description: The message to be displayed when hovering over the button (as a tooltip).
Type: string or null
Default: null (no hover message)

Using Hover Messages

Setting a custom hover message can provide additional context or information to users:

{
  "static_site": {
    "buttons": [
      {
        "text": "Download",
        "href": "https://example.com/file.pdf",
        "message": "Download the latest version of the document"
      }
    ]
  }
}

`authors`

Description: A list of authors for the target. Each author must be a string, whose value is defined in /site/docs/statics/authors/authors.json.
Type: array of string
Default: ["jacob_shing"] (an array containing a single string jacob_shing)
Accepted Values: Any string that is a valid key in the /site/docs/statics/authors/authors.json file, or a pseudo-author.

Pseudo-Authors

In addition to the authors defined in the authors.json file, you can also use pseudo-authors to control the behaviour and display of authors.

The following pseudo-authors are supported:

@unknown: Represents an unknown author. This will display as "Unknown Author" on the static site. Defining more than one @unknown in the authors list will display a plural form "Unknown Authors".
@do_not_sort: Preserves the order of authors as defined in the list. By default, authors are sorted alphabetically by their display_name, with the main author always appearing first, and unknown authors appearing at the end. Using this pseudo-author will disable sorting for non-main authors and non-unknown authors.

Main Author and Coauthors

Add an exclamation mark (!) before the author string to indicate that this is the main author of the target. At most one author can be the main author. Having more than one main author will cause the build pipeline to fail.

If no main author is specified, the first author in the alphabetical order will be treated as the main author.

All other authors are sorted in alphabetical order according to their display_name in the definition.

Also refer to the syntax reference for authors.json for the details about how to define authors in the authors.json file.

Computed Keys

Runtime Computed Keys

The following keys are computed dynamically at runtime by the metada parser. Their values are not stored in the metadata.json file, but can be accessed through the methods in the Metadata class.

Specifying these keys in the metadata.json file will have no effect.

`computed.tex_pkg_hash`

Description: The hash of the TeX packages used in the target. This is computed by traversing the \usepackage, \RequirePackage, and \documentclass commands in all .tex files in the source directory of the target. When build.no_latex is true, or when computed.is_alias is true, this value will be "0".
Type: string
Access By: metadata.computed.tex_pkg_hash.get()

`computed.is_alias`

Description: Whether the target is an alias to another target. Evaluates to true if static_site.alias_to is not null, false otherwise.
Type: boolean
Access By: metadata.computed.is_alias.get()

`computed.is_non_file_target`

Description: Whether the target is a non-file target. Evaluates to true if build.output_file is "NON_FILE_TARGET", false otherwise.
Type: boolean
Access By: metadata.computed.is_non_file_target.get()

Syntax Reference for metadata.json (v2)

Schema Overview

Changes from v1 to v2

Schema Fields

$schema

@metadata_file_version [Deprecated]

build.root_file

build.output_file

build.no_latex

build.requires

build.prebuild_command

build.build_command

build.postbuild_command

static_site.description

static_site.meta_description

static_site.custom_md_file

static_site.document_status

static_site.alias_to

static_site.pdf_viewer

static_site.buttons

static_site.buttons[i].{index}

static_site.buttons[i].{is_primary}

static_site.buttons[i].{text}

static_site.buttons[i].{icon}

static_site.buttons[i].{href}

static_site.buttons[i].{message}

authors