Skip to content

configuration.md

Latest commit

 

History

History
35 lines (22 loc) · 2.89 KB

configuration.md

File metadata and controls

35 lines (22 loc) · 2.89 KB

Configuration

There are various configuration files that can be used to customize the behavior for the generator. This page explains where to find them and how to use them.

The configuration files all have JSON schemas associated with them. Open them with an IDE like VSCode to get real-time validation.

Samples

This file can be found under settings/samples/samples.json. It is used to configure the generation process to include links to external code samples for different resource types. The schema is available here.

samples.json is not manually maintained. It can be updated by running scripts/UpdateSamples.ps1.

Note

This process is not currently automated. The script needs to be re-run to pick up the latest set of samples.

Config

This file can be found under settings/config/config.json, and can be used to configure the generation process. The schema is available here.

config.json contains central config for:

  • TocTitleMapping: used to generate custom page titles for different resource provider namespaces.
  • ExcludedProviders: a list of provider namespaces that should be excluded from docs generation.

Remarks

These set of files can be found under settings/remarks/<provider_namespace>/remarks.json, and can be used to add customizations to different doc pages. The schema is available here.

For example, remarks/microsoft.resources/remarks.json can be used to customize documents for the Microsoft.Resources provider namespace.

remarks.json contains the following configuration options:

  • DeploymentRemarks: Can be used to add custom markdown with information on deploying a particular resource type. For example, explaining some of the quirks.
  • ResourceRemarks: Can be used to add custom remarks in markdown format about a particular resource type. See here for an example of what the customized output looks like.
  • PropertyRemarks: Can be used to replace the description markdown for a particular resource type property.
  • BicepSamples: A list of .bicep files that will be added as samples to documentation. See here for an example of what the customized looks like.
  • TerraformSamples: A list of .tf files that will be added as samples to documentation.