nginx-ui/docs/guide/nginx-ui-template.md

Config Template

Nginx UI Template provides out-of-the-box configuration templates for users. In NgxConfigEditor, we offer a UI where users can quickly insert configurations from the template into the current configuration file. In this document, we will describe the file format and syntax of it.

The configuration templates are stored in template/block, and we welcome you to share your own configuration templates by open a PR.

::: tip Please note, you need to recompile the backend after modifying or adding new configuration files. :::

File Format

Nginx UI Template file consists of two parts: the file header and the actual Nginx configuration.

Below is a configuration template for hotlink protection, which we will use as a basis to introduce the file format and related syntax of Nginx UI Template.

# Nginx UI Template Start
name = "Hotlink Protection"
author = "@0xJacky"
description = { en = "Hotlink Protection Config Template", zh_CN = "防盗链配置模板"}

[variables.NoneReferer]
type = "boolean"
name = { en = "Allow Referer is None", zh_CN = "允许空 Referer"}
value = false

[variables.AllowReferers]
type = "string"
name = { en = "Allow Referers", zh_CN = "允许的 Referers"}
value = ""
# Nginx UI Template End

location ~ .*\.(jpg|png|js|css)$ {
    valid_referers {{- if .NoneReferer}} none {{- end}} blocked server_names {{if .AllowReferers}}{{.AllowReferers}}{{- end}};
    if ($invalid_referer) {
        return 403;
    }
}

File Header

The file header should be placed between # Nginx UI Template Start and # Nginx UI Template End, and should follow the toml syntax.

The file header includes the following fields:

Field	Description	Type	Required
name	Name of the configuration	string	Yes
author	Author	string	Yes
description	Desciption, uses a toml dictionary for multi-language support	toml dictionary	Yes
variables.VariableName.type	Variable type, currently supports boolean and string	string	No
variables.VariableName.name	Variable display name, is a toml dictionary to support multi-language	toml dictionary	No
variables.VariableName.value	Default value of the variable	boolean/string (according to type definition)	No

示例如下：

# Nginx UI Template Start
name = "Hotlink Protection"
author = "@0xJacky"
description = { en = "Hotlink Protection Config Template", zh_CN = "防盗链配置模板"}

[variables.NoneReferer]
type = "boolean"
name = { en = "Allow Referer is None", zh_CN = "允许空 Referer"}
value = false

[variables.AllowReferers]
type = "string"
name = { en = "Allow Referers", zh_CN = "允许的 Referers"}
value = ""
# Nginx UI Template End

The name, author, and description will be displayed in the configuration list as a summary.

When you click the "View" button, a dialog will appear, as shown below.

The input boxes and switches in the interface correspond to the variable types boolean and string.

Nginx Configuration

The Nginx configuration should be provided after the file header. This part will be parsed using the Go text/template library. This library provides powerful template generation capabilities, including conditional judgment, looping, and complex text processing, etc. For more information, please check Go Documentation.

The variables defined in the header can be used in this part, such as .NoneReferer and .AllowReferers. Please note that you need to define the variables in the header in advance before using them in this part.

Here is an example:

location ~ .*\.(jpg|png|js|css)$ {
    valid_referers {{- if .NoneReferer}} none {{- end}} blocked server_names {{if .AllowReferers}}{{.AllowReferers}}{{- end}};
    if ($invalid_referer) {
        return 403;
    }
}

When users input variable values in the app input boxes, the system will automatically generate new configuration content, as shown below:

In addition to the variables defined in the template header, we also provide macro-defined variables, as shown in the table below:

Variable Name	Description
HTTPPORT	Nginx UI listening port
HTTP01PORT	Port for HTTP01 Challenge

The variables above can be used directly in the configuration part without definition in the header.