Templating Reference

Farkle comes with a templating system which further helps developers work with the grammars they create. This system is a more powerful edition of both GOLD Parser's "Create Webpage" and "Create Skeleton Program" tools. In this guide, we will first see how to create an HTML page describing our grammar, and next we will see how to create our own templates. So, are you ready? Let's do this!

Preparing ourselves

Before we start, we first have to install Farkle's CLI tool from NuGet by opening a command prompt and running

dotnet tool install -g Farkle.Tools

Supported input types

The CLI tool can work with grammars from three kinds of files:

If we don't explicitly specify an input, the CLI tool will try to find a project in the current directory. If only one is found, it will be used. Otherwise the tool will fail with an error.

Dealing with multiple precompiled grammars

If the assembly or project passed to the CLI tool has only one precompiled grammar, it will be automatically used. If it has more than one however, we can tell it which one to use by adding a ::MyGrammar to the end of the input path.

To see an example, if you want to pick a specific grammar from an assembly or project, you can do it by writing MyAssembly.dll::MyGrammar or MyProject.csproj::MyGrammar respectively. If the current directory has only one project and you are bored to type it, you can write ::MyGrammar.

You can see the names of all precompiled grammars with the farkle list command which also takes an assembly, a project, or tries to find one on its own.

Creating HTML pages

For the rest of this guide, we will assume that we have a project with a precompiled grammar next to us. Once we build it, we can create an HTML page by running farkle new.

If everything went well, we will see a file named like MyAwesomeGrammar.html. It describes the grammar's syntax, its LALR states, its DFA states and more. If you are just watching, take a look at a sample HTML file generated for a JSON grammar to get a better idea.

These HTML files can be customized by omitting the state tables, the CSS styling, or by adding custom content at the end if their <head>. Run farkle new --help to get all the available options.

You can automatically generate an HTML file from your project's precompiled grammars by adding the following lines in it:


The HTML files will be generated to your project's build output directory and cannot be customized in any way. They are intended for development use; for most customizability it is recommended to use the CLI tool.

Creating your own templates

Instead of GOLD's custom and limited templating language, Farkle's templates use [Scriban], which features a much more powerful templating language. If you want to create your own templates, I recommend to first learn it from Scriban's official documentation.


Farkle's templates can use the following Scriban variables:

Scriban imports all properties of Farkle's objects but changes their names. Take a look at Farkle's built-in templates to get an idea how to write your own template, but keep in mind that the HTML templates use some constructs not available to custom templates, like Scriban's import statement and some other internal functions.


The templates can furthermore use the following functions:

Note: Precompiled grammars from an assembly or project are encoded in a format called EGTneo which is incompatible with GOLD Parser's EGT's format. When creating a template from an EGT file however, the to_base_64 function will return the Base-64 representation of that file.

Using custom templates

A custom template can be rendered by writing farkle new -t MyCustomTemplate.scriban. Of farkle new's arguments, custom templates only support -prop, as explained above.

So, I hope you enjoyed this little guide. If you did, don't forget to give Farkle.Tools a try, and maybe you feel especially willing to create some templates today, and want to hit the star button as well. I hope that all of you have a wonderful day, and to see you soon. Goodbye!