Tutorial Data Format

The Tutorial file format is a very simple command-based language which is very similar to YAML. There are commands for entering all various kinds of data needed to describe a mod and what versions are supported. Most commands are optional, and can be entered in any order. Anywhere this isn't true will be called out below.

There are several important files and directories related to tutorials:

• /static/data/<mod_slug>/tutorials/<tutorial_slug>.cg should contain the data file itself (described below).
• /static/browse/<mod_slug>/tutorials/<tutorial_slug>/icon.png should be a 160x160 image used to identify the tutorial throughout the site
• /static/browse/<mod_slug>/tutorials/<tutorial_slug>/ should contain any images or other resources referenced within the tutorial markup.

See: About Slugs for further details on how to determine the mod_slug and tutorial_slug referenced in these paths.

Example

schema: 1

section:
    title: What do gates do?
    content: <<-END
        BuildCraft gates are devices which can be attached to a pipe to detect and interact with objects 
        nearby. Gates can read a wide variety of conditions: that a nearby chest is full, or that a 
        [Combustion Engine](/browse/buildcraft/combustion_engine) is about to overheat. In reaction to 
        these conditions, gates can emit various kinds of signals (including redstone signals) to 
        control other gates and/or machines.
    END

section:
    title: An Example: Controlling Engines
    content: <<-END
        Before diving into all the details, let's look at a realistic example of what you might do with 
        gates. This is a small power plant driving a quarry.

        ![](./example_1_overview.png)

        Here are the important pieces of the build:

        1. The on/off switch for the entire operation.  Flipping the switch creates a redstone signal.
        2. A [Basic Gate](/browse/buildcraft/basic_gate/) attached to a [Structure Pipe]
            (/browse/buildcraft/structure_pipe) reads the redstone signal and generates a red pipe wire 
            signal.
        3. [Red Pipe Wire](/browse/buildcraft/red_pipe_wire) follows the [Cobblestone Kinesis Pipe]
            (/browse/buildcraft/cobblestone_kinesis_pipe), transmitting the signal throughout the rest 
            of the build.
        4. Another Basic Gate receives the red pipe wire signal and converts it back to a redstone 
            signal, thus turning the [Combustion Engine](/browse/buildcraft/combustion_engine)s on.
        5. The red pipe wire signal is also received by Basic Gates next to the [Redstone
            Engine](/browse/buildcraft/redstone_engine)s, turning them on as well, and causing both fuel 
            and water to flow into the engines.
        6. Finally, the power generated by the Combusion Engines flows into the [Quarry]
           (/browse/buildcraft/quarry/).
    END

video: J6-VUApZGQs, Buildcraft Gates Tutorial, Part 1

Basics

Each line of the file should usually contain a single command. Each command has the format: <command>: <arg>, <arg>, .... All of the available commands are described below. Multiple commands may be listed on the same line by separating them with ; characters. Comments are entered using the # character, which can itself be escaped if you need to use it in an item name. Blank lines are ignored. Whitespace is generally irrelevant outside item names, but following the conventions described above makes things easier.

The <<- syntax can be used to begin a "heredoc". The text which appears immediately after the <<- is used as a sentinel to determine when the heredoc is complete. All lines which appear between the line containing the <<- and the sentinel are considered to be part of the heredoc. In order to be recognized, the sentinel must appear by itself on a line. Heredocs automatically trim leading whitespace from the result, but will preserve indentation on lines indented more than others.

Command Reference

• schema: <version> (required)

  The data schema used by the file. The current version is: 1.

• section: (required)

  Begins a new section of the tutorial. Each is displayed as different visual block in the final page, and may have its own title and content.

• title: <text>

  The title of the section. This is displayed as a header immediately above the content for the section, and should generally only be a single sentence in length.

• content: <markdown> (required)

  The markdown-formatted content for the section. These can use both the [original syntax] (http://maruku.rubyforge.org/markdown_syntax.html), as well as the [Markdown Extra] (https://michelf.ca/projects/php-markdown/extra/) syntax. It is generally useful to use the heredoc syntax for this command, though it is not required.

  Images and other files may be referenced from the markdown document. Any files in /static/browse/<mod_slug>/tutorials/<tutorial_slug>/ are considered to be in the same directory as the markdown document and may be accessed without further path information. For example, the image at /static/browse/buildcraft/tutorials/gates_wires_and_chips/example_1_overview.png is referenced in the example above as ![](./example_1_overview.png).

  Links to other parts of Crafting Guide (e.g., other mods or items) should specify the full path to that item. So, for example, the Quarry in the example is referenced as: [Quarry](/browse/buildcraft/quarry/).

  At least one section command is required, though you may include as many additional section as you like.

• video: <YouTube ID>, <title>

  Includes an inline video in the tutorial page after all the content sections. Most of the usual YouTube chrome is hidden, including the title of the video. You may provide a title of your own.