##### Install the Official TapirMD Toolset

!  { ><
   :: The page is written in TapirMD (source is available __here__).
   }
       === here :: https://raw.githubusercontent.com/tapirmd/tmd/refs/heads/master/doc/pages/installation.tmd

This page shows the steps of installing and using the official __TapirMD__ toolset locally.
You can also experience the toolset __online__.

    === TapirMD:: index.html
    === online:: play.html

###+++++ Installation steps

    === Git :: https://git-scm.com/downloads
    === Go :: https://go.dev/dl/
    === Zig :: https://ziglang.org/download/
    === the TapirMD project :: https://github.com/tapirmd/tmd
    === the go-tmd project :: https://github.com/go101/tmd
    === download its source code :: https://github.com/tapirmd/tmd/tags

TapirMD hasn't yet reached version 1.0.0 (or even 0.1.0).
At this stage, building from source is the only way to run
the offcial TapirMD commands locally.

*. Install __Zig__, if haven't. The latest version tip (master) version is recommended.

*. Get the source code of __the TapirMD project__.
   You can clone it (install __Git__ if needed) or __download its source code__.

*. Open your terminal or command prompt, navigate to the TapirMD project folder,
   and run the following command to build the project:
   '''
   zig build -Doptimize=ReleaseSafe
   '''
   If the build is successful, the `tmd` command binary file will be generated
   in the `bin` folder under the project local `zig-out` folder.
   ;;;
   The `ReleaseSafe` optimization mode produces a fast binary with safety checks.
   For an even faster binary, use the `ReleaseFast` optimization mode instead:
   '''
   zig build -Doptimize=ReleaseFast
   '''

*. (Optional), copy the `tmd` binary file to a directory configured
   in the `PATH` enviroment variable, or add the path of
   the `bin` folder to the `PATH` enviroment variable,
   so that you can run the `tmd` command anywhere.

###+++++ Use the toolset

*  Run the following command to format TapirMD files:
   '''
    tmd fmt foo.tmd path-to-a-tmd-folder
   '''

*  Run the following command to geneate incomplete HTML files for embedding purpose.
   '''
    tmd gen foo.tmd path-to-a-tmd-folder
   '''

   -  Custom blocks can be enabled with the `--enabled-custom-apps` option:
      '''
    tmd gen --enabled-custom-apps=html foo.tmd path-to-a-tmd-folder
      '''
      Now, only `html` custom blocks can be enabled.

   -  Complete HTML files can be generated with the `--trial-page-css` option.
      For example, the following command will use the built-in example css.
      '''
    tmd gen ---trial-page-css=@ foo.tmd path-to-a-tmd-folder
      '''

*  Just run `tmd` without arguments to show the help information.