[Feature Request] Support docfx.yml in addition to docfx.json
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 11m
- Merged PRs (30d)
- 10
Description
**Is your feature request related to a problem? Please describe.**
Given that everything else in DocFX seems to be defined using YAML, e.g. `toc.yml`, `xrefmap.yml`, `filter.yml`, YAML-metadata in markdown files, etc, it is somewhat surprising to find `docfx.json` as the config entry point for DocFX.
Is there a reason for this? The only advantage I could come up with would be if the DocFX metadata was used directly in JavaScript or TypeScript as a data dictionary, but this doesn't seem to be a feature. With the complexity of possible configurations growing, and the absence of a formal JSON-schema specification or API for automatically manipulating the config file, the overwhelming majority of existing projects seem to be simply editing this file by hand.
If manual editing is the foreseeable future, then I would argue that YAML would be a much better suited format, with a much nicer human-readable syntax, support for multi-line strings (e.g. for writing `_appFooter`), etc.
**Describe the solution you'd like**
Support `docfx.yml` in addition to `docfx.json`. Given that `YamlDotNet` is already a project dependency, and that YAML is a superset of JSON, it should be possible to have a single set of domain classes that can be serialized into/out of either JSON or YAML. If the config file is described in a JSON-schema, as proposed in #8968 and #7736, the exact same schema could be used to support auto-completion of both YAML and JSON.
**Describe alternatives you've considered**
The only other alternative would be to write a JSON-schema for `docfx.json` and then use a dedicated pre-processing tool to convert `docfx.yml` to `docfx.json` at build time. The advantage of this alternative is it doesn't require any changes to DocFX and could be done using an externally developed tool. The disadvantage is having a forked implementation of a critical entry-point component is very risky for any long-term maintenance, especially in the lack of a formal JSON-schema to drive and validate the automations.
Contributor guide
Assessment
This issue has not been assessed yet.