Docfx: Table of content navigation on site

[Aaronontheweb]

I wrote up the full details here on SO: http://stackoverflow.com/questions/39112271/docfx-how-to-create-table-of-contents-navigation-on-site but thought I'd repost my issue here, since I can't find anything about this in the documentation.

I want to create a table of contents that looks like what DocFx has on their official site:

Using the default docfx init command using all of the default values my website looks like this upon build:

\

I've tried tampering with the toc.yml files with no such luck. How do I get this kind of navigation, and for that matter the top-level navigation with DocFx?

[qinezh]

Hi @Aaronontheweb , there's a sample documentation project which you can follow and have a try. Hope it could help you :smile:

[Aaronontheweb]

@qinezh thanks - I've looked through that. So why does the homepage not have a table of contents in that seed example, but the Articles homepage does?

[Aaronontheweb]

On top of not having the TOC appear in the documents, the top-level navigation doesn't appear to be working either. None of the metadata is being used to construct any sort of navigation at all. I've tried downgrading to older versions of docfx and this doesn't appear to work either.

Could you please add some documentation explaining how that navigation is constructed? Am I supposed to manually write out the HTML for linking everything together?

[qinezh]

Because the Articles folder in the repo contains a file toc.md. As for the breadcrumb, it's generated from toc.yml in repo root.

You can see the relative tutorial here

[Aaronontheweb]

Then could you help me understand why this is not working?

articles/ is where my markdown document goes and my api documentation .YML files get generated into api/.

Here's my .YML file - all of these paths are valid:

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

Here's my docfx.json, generated using the tool:

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ],
          "exclude": [
            "**/obj/**",
            "**/bin/**",
            "_site/**"
          ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
      "default"
    ],
    "postProcessors": [],
    "noLangKeyword": false
  }
}

The output I get when I run my docfx build step is still visually identical to what I posted earlier. I've tried switching between toc.md and toc.yml formats and I still get no navigation.

What I get instead is a totally separate toc.html web page, completely disconnected from every other piece of content:

And when I view it, it looks it has the missing piece of navigation I'm trying to get integrated onto every other page.

All of those links work! So why is this not being built into the output HTML pages for all of my actual content?

[superyyrrzz]

Hi @Aaronontheweb , can you try docfx --serve to visit the page from localhost:8080? If you open the local html file directly, the browser may preventing loading some files which will cause the missing navigation bar.

[Aaronontheweb]

Excellent that works - must be what you said: the local browser doesn't allow loading that content directly from the file system

[rkapl123]

Cool, this was exactly what I was searching for!

[larrynburris]

Same here. Thanks for working this one out @Aaronontheweb.

[tommikiviniemi-srs]

Any way of changing the output so this would work locally also?

I'd really like to provide a (versioned) zip of the documentation with my plugins, instead of just hosting the latest documentation.

Thanks.

[superyyrrzz]

@tommikiviniemi-srs try -t statictoc.