How to contribute

What Kind Of Contributions We Accept

We intentionally limit the scope of this tutorial to very basic techniques that are sufficient to get users started with recording, mixing, and exporting with Ardour. So we’ll gratefully accept patches that do not change the scope in any major way: bug fixes, better explanations, better illustrations etc. We also encourage translations of the ardour-tutorial.

Using Markdown Syntax And Extras

All text files use Markdown syntax with a few extras. We use a limited subset of available options and one shortcode specific to HTML5, a <figure> element (see here for more info). Another extra feature available in the template of choice is a so called shortcode for notice boxes that look like this:

Tip

Some text

We generally stick to two type of notice boxes: ’tip’ and ‘warning’.

The rest is really straightforward:

Single underscore like _Name_ makes italics and is used for UI elements like window captions.
Double asterisk like **OK** makes bolds and is reserved for button captions.
Backticks around some text are typically reserved for menu paths and filenames.

How to Submit Changes

The repository with this tutorial is available on GitHub. The general idea is that you fork the repository, make changes in a branch, then create a pull request. Please see here for a complete guide.

How To Create And Submit A Translation

The entire tutorial can be translated into a different language. Once you create a git branch to separate your work, here is what you do next.

The menu is stored in config.toml, inside the [Languages] section. For each language, that section has two parts:

The main part where names of chapters and pages chow up.
The ‘shortcuts’ menu with links to Ardour’s homepage, forum etc.

To translate the header of the main part, copy and paste the entire block that starts with [Languages.en] and then:

Change the language code in [Languages.en].
Translate the title.
Submit the name of the language that will show up in the drop-down list of available translations. We encourage you to use language or the local one, in your alphabet — whichever works for you.
Change the two-letter language code in the line that starts with landingPageURL.
Translate the caption of the homepage of the tutorial in the line that starts with landingPageName.

Thus

[Languages.en]
title = "Ardour tutorial"
weight = 1
languageName = "English"
landingPageURL = "/ardour-tutorial/en/"
#landingPageURL = "/"
landingPageName = "<i class='fas fa-home'></i> Home"

translates to e.g.:

[Languages.ru]
title = "Введение в Ardour"
weight = 1
languageName = "Russian"
landingPageURL = "/ardour-tutorial/ru/"
#landingPageURL = "/"
landingPageName = "<i class='fas fa-home'></i> Начало"

This main part of the menu will start automatically accumulating links to translated pages as you start adding pages with translations.

Use the same approach to translate the shortcuts menu. E.g. the link to Ardour’s website

[[Languages.en.menu.shortcuts]]
name = "<i class='fas fa-fw fa-home'></i> Ardour's homepage"
url = "https://ardour.org/"
weight = 11

becomes

#[[Languages.ru.menu.shortcuts]]
#name = "<i class='fas fa-fw fa-home'></i> Сайт Ardour"
#url = "https://ardour.org/"
#weight = 11

Please keep all translations of the menu in a single larger block.

Translating Chapters And Pages

All content lives inside the content folder where subfolders are names of chapters like Recording (recording), Mixing sessions (mixing-sessions) etc. Here is the general structure:

/content # The root folder for all content
/content/_index.en.md # The start page you see when you click Home
/content/chapter-folder/ # The folder for an entire chapter like "Recording"
/content/chapter-folder/_index.en.md # Chapter
/content/chapter-folder/page/ # Folder for a page in a chapter, e.g. "Understanding Routing"
/content/chapter-folder/page/index.md # Original text of that page in English
/content/chapter-folder/page/en/ # Screenshots created with English user interface

All text files have a language code right in the file name:

regular pages are named index.XX.md,
chapters are named _index.XX.md,

where XX is a two-letter language code like ‘de’ for German or ‘fr’ for French. You should be able to use four-letter codes as well, e.g. ‘pt_BR’ or ’es_AR’.

Supposing you want to translate the Getting Started chapter into French. Here is how you do it.

Create a copy of getting-started/_index.en.md and name it _index.fr.md. Now you should have _index.en.md and _index.fr.md in the same folder.
Translate _index.fr.md. If you already translated the main menu, you should be able to open the original page in English, switch the language to ‘Français’ and see your translated page.
Go to the starting-ardour subfolder, create a copy of index.en.md and name it index.fr.md and then translate it.
Repeat step 3 for all subfolders. This should give you the translation of an entire chapter on getting started with Ardour.

Translating User Interface Elements and Screenshots

If Ardour’s user interface is available in the language you are translating this tutorial into, it is generally up to you to decide if you refer to localized user interface or not.

We know that users are very passionate about both localized and non-localized UIs, so one approach you could take is to create localized screenshots, refer to localized user interface and then mention the English counterparts in parenthesis. Here is an example of a translation into German:

Nach dem Import einiger Sounds aus dem heruntergeladenen Sample-Pack (Bassdrum, Snare, Hi-Hat, Clap) sieht unsere Session so aus (in diesem Fall haben wir die Option Dateien als neue Spuren hinzufügen (EN: Add files as new tracks) verwendet und beim Start der Session eingefügt.

If you intend to create screenshots of localized user interface, please create a subfolder that’s named after a language code (two-letter of four-letter, whichever is applicable) and place your screenshots there. Having done so, please update references to screenshots in the text. E.g.

src="en/ardour7-save-template.png"