Docfx 3.0.0 How to get the TOC on the Index.html

Question

This question is the same as this question. But the OP answered his own question and it didn't help me.

I am trying to create a documentation similar to the Docfx site:

However, when I build the project, I get the index.html that looks like this:

My configuration is this:

Installed docfx.console as a nuget package in Visual Studio 2017 for the project.
The version of docfx is 2.58.0.
I'm building the project in Visual Studio, which produces the docfx output.

My folder configuration is:

+MyApp.sln
 |-MyApp
   MyApp.csproj
   docfx.json
   toc.yml
   index.md
 |-_site
 |- api
   index.md
   toc.yml
 |-articles
   intro.md
   toc.md

I can see that all the files are generating, but the TOC does not get put on to the index.html. The Docfx tutorial is not very helpful since it hasn't been upgraded to the newest version. For instance, docfx init does not run, I have to use docfx new conceptual. I have tried:

Running docfx new conceptual from a command prompt in the same directory as the docfx.json
Running docfx build from a command prompt in the same directory as the docfx.json
Running docfx serve _site --port 8182 from the same directory. However, when this is done, my browser tells me to check my proxy settings.

In everything I tried to do, I may have upgraded my docfx version in one place, but not in Visual Studio because when running docfx serve I get the following Content root path: But I am unsure of how to revert or if I need to.

I'm definitely in a locked-down security environment and I suspect that has something to do with it. Does anyone know of how what files I can alter, if any, to get the TOC on the same page as the index.html? I don't mind writing this by hand, if needed, if I'll only need to do it once in a configuration file.

Alexa Kirk · Accepted Answer · 2023-07-14T12:14:28.897

I finally found the problem. The issue for me was the folder configuration. I had to move my docfx.json, toc.yml, and index.md to the top level where my .sln file was because it was accessing multiple .csproj files. I didn't realize that the top-level toc.yml could only access folders under it's current location.

Furthermore, the top-level toc.yml will only create the menu items across the top of the page. The lower-level toc files will create the TOC on the left side of the page.

It took some digging into the tutorial to figure this out.

score 0 · Answer 2 · answered Sep 01 '21 at 01:10

0

The only way I have ever been able to get that to happen:

Change articles/toc.md to articles/toc.yml:

 - name: Home
   href: ../index.md (or wherever index.md relative to articles/ is)
 - name: Intro
   href: intro.md

Add this to docfx.json > build > content > files (the one that includes articles):

"**/*.yml",

Take the reference to home out of toc.yml (at root):

- name: Articles
  href: articles/
- name: API
  href: api/

I'm not totally clear on your file structure, but this is the idea.

answered Sep 01 '21 at 01:10

hcdocs

1,078
2
18
30

Thank you for your response. I added your changes one at a time, and built the project in between each. The addition of `"**/*.yml"` to the build > content > files (articles one) resulted in a build error: "The command "".\docfx.exe "/docfx.json" -o "" -l "log.txt" --logLevel "Warning" -f" exited with code 1." Any clues? – Alexa Kirk Sep 01 '21 at 12:28
I didn't look close enough at how your files are organized. The idea is that the toc.yml file in the articles folder needs to be included in docfx.json. It looks like your docfx.json is in a MyApp directory, so docfx.json may need to point to something like `../articles/*.yml`. – hcdocs Sep 01 '21 at 18:39
If it helps at all, I tested using the directory structure of the [docfx-seed](https://github.com/docascode/docfx-seed) test project. – hcdocs Sep 01 '21 at 18:41
Thanks. The docfx.json includes the `/articles/*.yml`. I also tested on the docfx-seed test project and I got the same issue. I think it's because of my high-security environment. It won't allow me to serve the result on any port and it won't allow the scripts to run. I'll probably just build my own index.html and point to the rebuilt html files in the _site/api folder. – Alexa Kirk Sep 02 '21 at 16:47

Patrice Calvé · Answer 3 · 2021-09-28T17:42:33.310

0

For me, what worked was a change to the root toc.yml. The href with a file name like /index.md does not work, but with the folder it does.

Wrong: root toc.yml

- name: Articles
  href: articles/index.md
- name: API
  href: api/index.md

Good: root toc.yml

- name: Articles
  href: articles/
- name: API
  href: api/
  topicHref: api/some.md

edited Sep 28 '21 at 17:42

answered Sep 23 '21 at 14:52

Patrice Calvé

674
6
12

Thank you. I already have the root toc.yml as your "Good" file. That doesn't work for me. – Alexa Kirk Sep 24 '21 at 18:08
Try name+href (like above) or name+href+topicHref. ```-name: name href: path/ topicHref: path/file.md ``` – Patrice Calvé Sep 28 '21 at 17:40

score 0 · Answer 4 · answered Jul 14 '23 at 11:14

You relative source paths do not resolve. This is because when using relatives paths they are relative to the DocFx working directory, which is the directory of the DocFx project by default.

The solution is to change the working directory.

For example when the following folder structure is given:

Drive_C
  Solution_Folder
    myApplication.sln
    Project1_Folder
      project1.csproj
    Project2_Folder
      project2.csproj
    DocFx_Folder
      index.md
      ...

... then you must move the working directory one level up. You can use the src property in the docfx.json file. Either use relative path notation or absolute:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "Project1/**.csproj",
            "Project2/**.csproj"
          ],
          "exclude": [],
          "src": ".."  <==== Relative path: Move working directory to parent directory,
          "src": "Drive_C/Solution_Folder/"  <==== Absolute path: Move working directory to parent directory
        }
      ],
      "dest": "api",

Docfx 3.0.0 How to get the TOC on the Index.html

4 Answers4