Website Development Reference
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.
Start any .md file with a 2 triple-dashed lines front matter, otherwise Jekyll will copy the original md file into the resulting
Opcode files should include:
layout: sfz/opcodevariable 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.ymlto 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.:
Don’t use ‘<’ and ‘>’ in md files to avoid the parser to generate wrong html code, use ‘‹’ and ‘›’ instead.
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.
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.
/_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
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.
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.
SFZ related YAML files
/_data/sfz/ directory contains all YAML files used for SFZ related data.
headers section is used by the
/headers/index.md description tables:
- name: The header name
- version: The SFZ version, currently can be one of:
- SFZ v1
- SFZ v2
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.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.
- type_name: Value type (string, integer, float etc.),
- default: An optional default value.
- min: An optional range minimum value.
- max: An optional range maximum value.
- unit: Value unit (seconds, decibels, cents etc.).
- type_name: Value type (string, integer, float etc.),
envelope: true (bool, without double quotes) if unspecified but present, otherwise the name of modulation (string).
lfo: same as for envelope.
- name: the ccN related opcode event name.
- version: the opcode modulation SFZ version
For more details, check the file for additional variable options.