Point "Improve this Doc" button to default branch

[pvandervelde]

Is it possible to point the "Improve this Doc" button to a default branch?

I'm using GitFlow for as the workflow for my repository and on top of that builds are never done on master, just on the final commit on the release or hotfix branch. This means that the "Improve this Doc" button in any documentation build that this time also points to the release or hotfix branch. However this branch is only temporary.

So I would like to point the button to the develop branch. Is there a way to do this in the configuration?

[superyyrrzz]

You can add newFileRepostiry property to globalMetadata in docfx.json:

    "globalMetadata": {
      "newFileRepository": {
        "branch": "yourBranch"
      }
    },

[pvandervelde]

So that seems to work in the API documentation part but not in the general documentation part. Both the "Improve this Doc" button in the general documentation and the "View Source" button in the API documentation point to the branch I'm building on. The "Improve this Doc" button in the API documentation points to the branch I specified in the docfx.json file.

My doxfx.json file looks like this:

{
    "metadata": [
        {
            "src": [
                {
                    "cwd": "../../",
                    "exclude": [
                        "**/obj/**",
                        "**/bin/**",
                        "_site/**"
                    ],
                    "files": [
                        "src/**/*.csproj"
                    ]
                }
            ],
            "dest": "obj/api"
        }
    ],
    "build": {
        "content": [
            {
                "files": [
                    "api/**.yml"
                ],
                "cwd": "obj"
            },
            {
                "files": [
                    "api/*.md",
                    "articles/**.md",
                    "toc.yml",
                    "*.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "dest": "_site",
        "globalMetadata": {
            "newFileRepository": {
                "branch": "develop"
            },
            "_appFooter": "Copyright (c) - TheNucleus 2013 - 2016. All rights reserved."
        },
        "overwrite": [
            {
                "files": [
                    "apidoc/**.md"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "resource": [
            {
                "files": [
                    "images/**"
                ],
                "exclude": [
                    "obj/**",
                    "_site/**"
                ]
            }
        ],
        "template": [
            "default"
        ]
    }
}

Did I get my configuration incorrect?

[superyyrrzz]

Got your ideas. Your docfx.json is correct, but currently this can only change the branch name when creating a new file on GitHub. We will investigate this.

[pvandervelde]

What do you mean with 'creating a new file on GitHub'?

[superyyrrzz]

"Improve this Doc" links to the conceptual file of the current document. If not found, it will link to a "New File" URL on GitHub.

• For conceptual documents, as the content in pages are all from conceptual files, so the conceptual file must already exists, which lies in the current branch.
• For reference documents, as the content is from yml files, mostly the conceptual file doesn't exist. So it leads to the "New File" URL, where newFileRepository takes effects.

[superyyrrzz]

@pvandervelde implemented in dev branch. Now you can use the _gitContribute to switch the branch for all the Improve this Doc. Here's an sample:

"globalMetadata": {
      "_gitContribute": {
        "repo": "repoURL",
        "branch": "branchName",
        "path": "overwriteFilePath"
      }
    },

In your case, you need to set "branch": "develop"

[pvandervelde]

Sweet. I'll wait for the next release but that's exactly what I wanted.

[guardrex]

@superyyrrzz Question on this ...

We have the same problem for the new Blazor docs repo (docs at: http://blazor.net). We're working on master but using the live branch for our live docs. We want the same set up ... "Improve this doc" should open for our readers to edit on the master branch.

I understand everything but one thing ..... What do we need for the overwriteFilePath?

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "repo": "https://github.com/aspnet/Blazor.Docs",
    "branch": "master",
    "path": "overwriteFilePath"
  }
}

[EDIT] I found this at https://github.com/dotnet/docfx/blob/2a787812343d8198bb4928213ea120c7f8b00bf5/Documentation/tutorial/docfx.exe_user_manual.md ...

_gitContribute
Customize the Improve this Doc URL button for public contributors. Use repo to specify the contribution repository URL. Use branch to specify the contribution branch. Use apiSpecFolder to specify the folder for new overwrite files. If not set, the git URL and branch of the current git repository will be used.

It looks like you changed path to apiSpecFolder and that we don't need to specify the branch or the apiSpecFolder. Looks like you just need us to do this ...

"globalMetadata": {
  "newFileRepository": {
    "branch": "master"
  },
  "_gitContribute": {
    "branch": "master"
  }
}

[superyyrrzz]

@guardrex overwriteFilePath is for reference page's overwrite document. If someone want to contribute to a class' summary, improve this doc will link to a page to create an overwrite file under overwriteFilePath folder.