Skip to content

Commit

Permalink
docs: add reference TOC docs
Browse files Browse the repository at this point in the history
  • Loading branch information
yufeih committed Jul 22, 2023
1 parent ee776de commit d0b4992
Showing 1 changed file with 54 additions and 4 deletions.
58 changes: 54 additions & 4 deletions docs/docs/table-of-contents.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,6 @@ The YAML document is a tree of TOC nodes, each of which has these properties:
- `uid`: The uid of the article. Can be used instead of `href`.
- `expanded`: Expand children on load, only works if the template is `modern`.

## Navigation Bar

The `toc.yml` file in the `docfx.json` folder will be used to fill the content of the navigation bar at the top of the page.

## Nested TOCs

To nest a TOC within another TOC, set the `href` property to point to the `toc.yml` file that you want to nest. You can also use this structure as a way to reuse a TOC structure in one or more TOC files.
Expand Down Expand Up @@ -66,3 +62,57 @@ Reference
├─ System.String
├─ System.Float
```

## Reference TOCs

To reference another TOC without embeding it to a parent TOC using nested TOCs, set the `href` property to point to the directory that you want to reference and end the string with `/`, this will generate a link pointing to the first article in the referenced TOC.

Consider the following folder structure:

```
toc.yml
├─ System
├─ toc.yml
├─ System.Collections
├─ toc.yml
```

_toc.yml_:

```yml
- name: System
href: System/
- name: System.Collections
href: System.Collections/
```

This structure renders as follows:


```yml
System # Link to the first article in System/toc.yml
System.Collections # Link to the first article in System.Collections/toc.yml
```

## Navigation Bar

The `toc.yml` file in the `docfx.json` folder will be used to fill the content of the navigation bar at the top of the page. It usually uses [Reference TOCs](#reference-tocs) to navigate to child pages.

The following example creates a navigation bar with two _Docs_ and _API_ entries:

```
toc.yml
├─ docs
├─ toc.yml
├─ api
├─ toc.yml
```

_toc.yml_:

```yml
- name: Docs
href: docs/
- name: API
href: api/
```

0 comments on commit d0b4992

Please sign in to comment.