Skip to content

Website Development Reference

Introduction

This page has the purpose to document the SFZ Format project website and give references and rules for maintainance.

GitHub and Travis-CI

The webpage is hosted on GitHub using Git SCM as content management, using 2 git repositories: source and master. The source repository is used for the website source files written in Markdown format and Liquid language, which are used by Jekyll, a static pages website generator created and used by GitHub for hosting project websites. The master repository is used to store the generated files that are built externally by Travis Continuous Integration service. Travis-CI was choosed instead GitHub Pages to enable the use of Jekyll custom plugins required for our purposes, following their GitHub Pages Deployment documentation.

Rules

  • Start any .md file with a 2 triple-dashed lines front matter, otherwise Jekyll will copy the original md file into the resulting _site directory.

    Opcode files should include:

    • a layout: sfz/opcode variable to specify the required layout to build the resulting html page
    • the page language code
    • optionally, the title of the page if different than the page name (see the example below).
  • Each opcode file must have also an entry in the syntax.yml db file.

  • Using block code three back ticks even with a single line, inline code is used for opcode keywords highlights.

  • Using spaces instead of tabs for indentation in pages, mostly on _config.yml to avoid issues / unwanted results.

  • Using 80 characters per line limit for a better reading.

  • Using a naming convention for numbered opcodes starting with N following with X Y Z, e.g.: egN_timeX_onccY

  • Don’t use ‘<’ and ‘>’ in md files to avoid the parser to generate wrong html code, use ‘‹’ and ‘›’ instead.

Content

Opcode File Example

In case the opcode doesn’t have any modulation and it has some associated opcode like on_loccN / on_hiccN, then using title is the right choice. Otherwise use opcode_name, so a modulation documentation file (a symlink to the opcode it modulates in source code) will use the correct references.

---
layout: "sfz/opcode"
lang: "en"
title: "lovel / hivel"
---
(Here the auto-generated brief text description from syntax.yml db...)

This is just an example for an opcode extended description to be written in some
/opcodes/lovel.md markdown file.
This text is readable on any editor, with low or high resolutions.

## Examples

```
lovel=value1
hivel=value2
```

(Here the auto-generated description table from syntax.yml db...)
---
layout: "sfz/opcode"
lang: "en"
opcode_name: "volume"
---
...

## Examples

```
...
```

(auto-generated table ->) Modulations: volume_onccN ...

YAML Configuration Files

The main _config.yml configuration file is placed in the root of the source repo. It is used by Jekyll to store its configuration options, but it can also be used for user custom options as well. Other configuration files are placed in the _data directory, used for other website contexts, like translation strings, navigation menu, aside blocks, and other SFZ related data files.

Translation files

The /_data/locale/ directory contains all files used for website language translation subdivided by language codes as subdirectories. Currently each language translation subdirectory contains 2 files:

  • layout.yml: contains both the navigation menu links and the aside card blocks strings
  • translation.yml: contains all the language related translation strings used by default in the website pages.

layout.yml navigation and cards section

The navigation section is used by the _includes/navigation.html layout page to build the navigation menu. It recognizes the following variable structure:

  • title: The menu title
  • type: The menu type, can be normal for simple links or dropdown for submenus, identified by an arrow down icon.
  • url: Normal links only, the URL of the link.
  • pages: Submenus container. An empty item, using just a hyphen, creates a menu separator.

The cards section is used by the _includes/cards.html layout page to build the aside card blocks on the right side of most of the website pages to place various internal and external links. It’s very similar to the navigation one with few differences:

  • title: The card header title
  • icon_type: A Font Awesome icon type name, e.g. “github”
  • icon_category: The category of the FA icon
    • fas: solid icon
    • fab: brand icon
  • links: The contained card links.

The /_data/sfz/ directory contains all YAML files used for SFZ related data.

syntax.yml

The headers section is used by the _includes/sfz/headers-table-generator.html to build /headers/index.md description tables:

  • name: The header name
  • version: The SFZ version, currently can be one of:
    • SFZ v1
    • SFZ v2
    • ARIA

The opcodes section is used by different files as database information for all known opcodes, including extension ones.

The data is accessible from the site.data.sfz.syntax.opcodes and site.data.sfz.syntax.headers Liquid variables.

There are various possible variables, which most are not mandatory, so if some opcode doesn’t includes a feature, it can be omitted, resulting in Liquid code as variable-name == nil.

Currently possible values are:

  • name: the opcode name.

  • short_description: a brief opcode description used to describe all opcodes included in the related SFZ version/extension page.

  • version: SFZ version or extension (same as for headers).

  • alias: if the opcode has some alias in other specification version.

  • value:
    • type_name: Value type (string, integer, float etc.), mandatory for opcodes.
    • default: An optional default value.
    • min: An optional range minimum value.
    • max: An optional range maximum value.
    • unit: Value unit (seconds, decibels, cents etc.).
  • modulation:
    • envelope: true (bool, without double quotes) if unspecified but present, otherwise the name of modulation (string).

    • lfo: same as for envelope.

    • midi_cc:

      • name: the ccN related opcode event name.
      • version: the opcode modulation SFZ version

For more details, check the file for additional variable options.