Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Update docfx.json config reference document #9813

Merged
merged 2 commits into from
Mar 27, 2024
Merged

chore: Update docfx.json config reference document #9813

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4544bd1
chore: update config reference document
filzrev Mar 25, 2024
39e2c90
chore: update config reference document
filzrev Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 30 additions & 4 deletions docs/reference/docfx-json-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ The `docfx.json` file indicates that the directory is the root of a docfx projec
}
```

## Global properties
## Global properties

### `rules`
## `rules`

Overrides default log message severity level. Key is the log code, supported values are `verbose`, `info`, `suggestion`, `warning`, `error`:

Expand Down Expand Up @@ -148,6 +148,7 @@ Templates are used to transform YAML files generated by `docfx` to human-readabl
}
}
```

```json
{
"build": {
Expand All @@ -166,7 +167,6 @@ The themes applied to the documentation. Theme is used to customize the styles g

Theme is to provide general styles for all the generated pages. Files inside a theme will be generally copied to the output folder. A typical usage is, after YAML files are transformed to HTML pages, well-designed CSS style files in a Theme can then overwrite the default styles defined in template, e.g. `main.css`.


### `xref`

Specifies the urls of xrefmap used by content files. Currently, it supports following scheme: http, https, file.
Expand Down Expand Up @@ -199,6 +199,22 @@ Sets the max parallelism. Setting 0 (default) is the same as setting to the coun

Sets the parameters for the markdown engine, value is a JSON object.

### `customLinkResolver`

Set the name of the `ICustomHrefGenerator` derived class.

### `groups`

Specifies the output folder of specified group name.

```json
"groups":
"v1": {
"dest": "output_dir_v1"
}
}
```

### `sitemap`

Specifies the options for generating [sitemap.xml](https://www.sitemaps.org/protocol.html) file:
Expand Down Expand Up @@ -320,6 +336,12 @@ Specifies the output folder of the generated metadata files relative to `docfx.j

If set to true, DocFX would not render triple-slash-comments in source code as markdown.

### `references`

Specify additinal assembly reference files.
This settings is used when generating metadata from DLLs or source files.
Solution or project file-based metadata generation does not use this property.

### `filter`

Specifies the filter configuration file, please go to [How to filter out unwanted apis attributes](../tutorial/howto_filter_out_unwanted_apis_attributes.md) for more details.
Expand All @@ -332,6 +354,10 @@ Disables the default filter configuration file.

Disables generation of view source links.

### `codeSourceBasePath`

Specify the base directory that is used to resolve code source (e.g. `<code source="Example.cs">`).

### `properties`

Specifies an optional set of MSBuild properties used when interpreting project files. These are the same properties that are passed to msbuild via the `/property:name=value` command line argument.
Expand Down Expand Up @@ -372,7 +398,7 @@ Specifies how member pages are organized:

When enabled, continues documentation generation in case of compilation errors.

### `EnumSortOrder`
### `enumSortOrder`

Specifies how enum members are sorted:

Expand Down
5 changes: 2 additions & 3 deletions src/Docfx.App/Config/BuildJsonConfig.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,14 +202,13 @@ internal class BuildJsonConfig
public string CustomLinkResolver { get; set; }

/// <summary>
/// Define groups.
/// Specifies the output folder of specified group name.
/// </summary>
/// <example>
/// <code>
/// groups:{
/// "v1": {
/// "dest": "v1",
/// "extraMetadata01": {}
/// "dest": "output_dir_v1"
/// }
/// }
/// </code>
Expand Down
9 changes: 5 additions & 4 deletions src/Docfx.Dotnet/MetadataJsonConfig.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,10 +118,11 @@ internal class MetadataJsonItemConfig
[JsonPropertyName("shouldSkipMarkup")]
public bool? ShouldSkipMarkup { get; set; }

[JsonProperty("raw")]
[JsonPropertyName("raw")]
public bool? Raw { get; set; }

/// <summary>
/// Specify additinal assembly reference files.
/// This settings is used when generating metadata from DLLs or source files.
/// Solution or project file-based metadata generation does not use this property.
/// </summary>
[JsonProperty("references")]
[JsonPropertyName("references")]
public FileMapping References { get; set; }
Expand Down