CODEWITHSUNDEEP
c#visual-studio-2017docfx
zynovij
zynovij

Reputation: 195

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

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: Docfx home page

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

My configuration is this:

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:

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: 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.

Upvotes: 1

Views: 3883

Answers (4)

zynovij
zynovij

Reputation: 195

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.

Upvotes: 2

user21970328
user21970328

Reputation:

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",

Upvotes: 0

Patrice Calv&#233;
Patrice Calv&#233;

Reputation: 694

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

Upvotes: 0

hcdocs
hcdocs

Reputation: 1309

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.

Upvotes: 1

Related Questions