Configuration

Most modules will have some form of configuration, which should be specified in this section. Configurations are usually specified using environment variables, configuration maps, runtime flags, configuration servers etc.

For simple configuration options, they should be clearly enumerated here in a table. If a table is not ideal to display your configuration options, you may use other alternatives as long as the expected type, default, and description is included.

As always, if you need to split your configuration information up into multiple files, feel free to add more files to this section.

Example Configuration Table

The following is an example of configuration rendered using a markdown table - this is good for config maps in JSON/YAML where the data type might matter:

Name	Type	Default	Description
title	string	'Sample Config Title'	The title that is displayed for your this example application.
outputDir	string	'./'	The path to output something from this example application.
isSecure	boolean	false	Set to true if you want your example application to be secure.
friends	string[]	[]	The list of friends you wish you had.
enemies	string[]	[ "Jon Snow"]	The list of enemies you currently have.

For environment variables, the type column can be omitted as they are always strings.

Example usage in JSON:

{
    "title": "Sample Config Title",
    "outputDir": "./",
    "isSecure": false,
    "friends": [],
    "enemies": [ "Jon Snow" ]
}

Example usage in YAML:

title: Sample Config Title
outputDir: ./
isSecure: false
friends: []
enemies:
    - Jon Snow

Example using markdown headers

For more complex configurations that require longer descriptions, you should segregate them with markdown headers. The advantage of using markdown headers is that it also creates anchor links you can use to share directly to the section like this for title:

title

• Type: string

• Default: 'Sample'

• The title that is displayed for your this example application. This longer example might include an image of how the title looks like:

outputDir

• Type: string

• Default: './'

• The path to output something from this example application.

isSecure

• Type: boolean

• Default: false

• Set to true if you want your example application to be secure.

  caution

  In some cases you might also need to call include admonitions like this, which won't fit in a table.

friends

• Type: string[]

• Default: []

• The list of friends you wish you had.

You might need to elaborate on your configuration, like how you wish you were friends with Princess Diana or Jeremy Clarkson. In which case you should pass in [ 'Princess Diana', 'Philomena Cunk' ] in this example.

enemies

• Type: string[]

• Default: [ 'Jon Snow' ]

• The list of friends you wish you had.

The list of enemies you currently have.