Schema file for toc? #7736
Labels
toc
Navigation components like menus, TOC and breadcrumbs
Comments
|
The schema file would be something like this: {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://dotnet.github.io/docfx/toc.schema.json",
"title": "Schema for DocFx Table-Of-Content Files (toc.yml)",
"description": "Reference: https://dotnet.github.io/docfx/tutorial/intro_toc.html",
"additionalProperties": false,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Specifies the title of the TOC Item.",
"type": "string"
},
"href": {
"description": "Specifies the navigation path of the TOC Item. If href is not specified, the TOC Item serves as a container to parent its children TOC Items. If href is an absolute path, the TOC Item navigates to that specified path. If a TOC Item is linking to a relative path, there are three cases: 1. Linking to another TOC File, for example, href: examples/toc.md. 2. Linking to a folder, which means, the value of the link ends with / explicitly, for example, href: examples/ 3. Linking to some local file.",
"type": "string"
},
"topicHref": {
"description": "Specifies the topic href of the TOC Item. It is useful when href is linking to a folder or TOC file or tocHref is used.",
"type": "string"
},
"topicUid": {
"description": "Specifies the uid of the referenced file. If the value is set, it overwrites the value of topicHref.",
"type": "string"
}
}
}
} |
|
The schema has to be defined recursively so that TOC.yml can have any depth of nested items. TOC.yml is read by TocHelper.LoadYamlToc, which allows either TocViewModel or TocRootViewModel. The schema document could define schemas for TocViewModel, TocRootViewModel, and TocItemViewModel, and then allow either TocViewModel or TocRootViewModel at the top level. The documentation of Untested: {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "toc.yml for DocFX",
"$defs": {
"TocViewModel": {
"$comment": "Microsoft.DocAsCode.DataContracts.Common.TocViewModel",
"title": "Array of TOC Item Objects",
"type": "array",
"items": {
"$ref": "#/$defs/TocItemViewModel"
}
},
"TocRootViewModel": {
"$comment": "Microsoft.DocAsCode.DataContracts.Common.TocRootViewModel",
"title": "TOC Item Objects with metadata",
"description": "This feature was added in <https://github.com/dotnet/docfx/pull/1731>.",
"type": "object",
"properties": {
"items": {
"$comment": "TocRootViewModel.Items",
"$ref": "#/$defs/TocViewModel"
}
},
"additionalProperties": {
"$comment": "TocRootViewModel.Metadata"
}
},
"TocItemViewModel": {
"$comment": "Microsoft.DocAsCode.DataContracts.Common.TocItemViewModel",
"title": "TOC Item Object",
"description": "<https://dotnet.github.io/docfx/tutorial/intro_toc.html#toc-item-object>",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"$comment": "TocItemViewModel.Name",
"title": "Title of TOC item",
"description": "Specifies the title of the TOC Item.",
"type": "string"
},
"href": {
"$comment": "TocItemViewModel.Href",
"title": "Path of folder, file, or TOC file",
"description": "Specifies the navigation path of the TOC Item. If \"href\" is not specified, the TOC Item serves as a container to parent its children TOC Items. If \"href\" is an absolute path, the TOC Item navigates to that specified path. If \"href\" is a relative path, see <https://dotnet.github.io/docfx/tutorial/intro_toc.html#href-in-detail> for details.",
"type": "string"
},
"items": {
"$comment": "TocItemViewModel.Items",
"$ref": "#/$defs/TocViewModel"
},
"topicHref": {
"$comment": "TocItemViewModel.TopicHref",
"type": "string"
},
"topicUid": {
"$comment": "TocItemViewModel.TopicUid",
"type": "string"
},
"homepage": {
"$comment": "TocItemViewModel.Homepage",
"description": "Use \"topicHref\" instead.",
"type": "string",
"deprecated": true
},
"uid": {
"$comment": "TocItemViewModel.Uid",
"description": "Use \"topicUid\" instead.",
"type": "string",
"deprecated": true
},
"homepageUid": {
"$comment": "TocItemViewModel.HomepageUid",
"description": "Use \"topicUid\" instead.",
"type": "string",
"deprecated": true
},
"displayName": {
"$comment": "TocItemViewModel.DisplayName; undocumented",
"type": "string"
},
"originalHref": {
"$comment": "TocItemViewModel.OriginalHref; undocumented",
"type": "string"
},
"tocHref": {
"$comment": "TocItemViewModel.TocHref; almost undocumented",
"type": "string"
},
"originalTocHref": {
"$comment": "TocItemViewModel.OriginalTocHref; undocumented",
"type": "string"
},
"originalTopicHref": {
"$comment": "TocItemViewModel.OriginalTopicHref; undocumented",
"type": "string"
},
"includedFrom": {
"$comment": "TocItemViewModel.IncludedFrom; undocumented",
"type": "string"
},
"originallHomepage": {
"$comment": "TocItemViewModel.OriginalHomepage; undocumented; misspelled",
"type": "string"
}
},
"patternProperties": {
"^name\\.": {
"$comment": "TocItemViewModel.NameInDevLangs",
"type": "string"
}
},
"additionalProperties": {
"$comment": "TocItemViewModel.Metadata"
},
"dependentSchemas": {
"topicHref": {
"$comment": "\"topicHref\" should be used instead of the deprecated \"homepage\", not with it.",
"properties": {
"homepage": false
}
},
"topicUid": {
"$comment": "\"topicUid\" should be used instead of the deprecated \"uid\" and \"homepageUid\", not with them.",
"properties": {
"uid": false,
"homepageUid": false
}
}
}
}
},
"oneOf": [
{
"$ref": "#/$defs/TocViewModel",
"title": "Without metadata"
},
{
"$ref": "#/$defs/TocRootViewModel",
"title": "With metadata"
}
]
} |
|
Great. I made the property "TocItemViewModel": {
"$comment": "Microsoft.DocAsCode.DataContracts.Common.TocItemViewModel",
"title": "TOC Item Object",
"description": "<https://dotnet.github.io/docfx/tutorial/intro_toc.html#toc-item-object>",
"type": "object",
"required": [
"name", "href"
],Then it works like a charm.
|
I was wrong. The property |
|
Based on
it seems that DocFX v2 deprecates
I don't see v3 using any of the "original" properties, so those could be disallowed in the schema. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Hi, I am using VS Code to work on my content in DocFx. Often I have to write proper toc files . In VSCode there is an inline checker against the yaml-schemas, but it looks up a wrong schema and then alle the file is red underlined.
Is there a schema file around for the toc.yml that I can configure for my toc files??
The text was updated successfully, but these errors were encountered: