##### 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/documentation/pages/installation.tmd

This page outlines the steps to install the official TapirMD toolchain
and introduces some basic commands it provides.

You can also try TapirMD formatting syntax __online__.

    === online:: play.tmd

###+++++ 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 minor 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
   '''
   ;;;
   Or you can just build a debug version:
   '''
   zig build
   '''
   The debug version will print more readable information when problems are encountered.
   As the toolchain is still in its early development phase, bugs are inevitable.
   Bug reports are seriously welcome __ here`` https://github.com/tapirmd/tmd/issues __.

*. (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 toolchain

*  Run `tmd` without arguments to show the help information.

*  Run the following command to format `.tmd` files:
   '''
    tmd fmt foo.tmd path-to-a-tmd-folder
   '''
   ;;;
   Run `tmd fmt` with no arguments to format all `.tmd` files within the current directory:

*  Run the following command to generate HTML snippet files for embedding purpose
   in the same directories of corresponding `.tmd` files.
   '''
    tmd gen foo.tmd path-to-a-tmd-folder
   '''
   ;;;
   Run `tmd gen` with no arguments to generate HTML snippet files for all `.tmd` files
   within the current directory:

*  Run the following command to generate full HTML page files in the same directories
   of corresponding `.tmd` files.
   '''
    tmd gen-full-page foo.tmd path-to-a-tmd-folder
   '''
   ;;;
   Run `tmd gen-full-page` with no arguments to generate full HTML page files for all `.tmd` files
   within the current directory:

*  Run the following commands to build a TapirMD project located at the specified directory
   and output target files in `@tmd-build` folder in the workspace directory of the project.
   '''
    tmd build project-dir
    tmd build project-config-file
   '''
   ;;;
   Run `tmd build` with no arguments to build the TapirMD project located at the current directory.