Docfx: Integrate DocFx with GitHub Pages

[olegburov]

When DocFx v3 is ready and Microsoft acquisition of GitHub is closed, I would like to use DocFx with GitHub Pages in addition to Jekyll.

What do you think guys?

[yufeih]

I personally love this idea, it could make publishing to GitHub Pages a lot smoother, but I'd like to see it as an app on top of an open platform, instead of a first class offering from GitHub.

[txwizard]

I devised a way to accomplish that, using only the current production version and my imagination. The documentation is at https://txwizard.github.io/WizardWrx_NET_API/, and the project repository is at https://github.com/txwizard/WizardWrx_NET_API.

My solution was fairly straightforward.

1. Create the docfx_project directory and generate the documentation as instructed.

2. Create a Windows Junction reparse point at docfx_project\_site that points to a docs directory off the main solution directory.

3. Ensure that the docfx_project directory contains a 1-byte .gitignore that contains a single asterisk, so that the entire directory is ignored.

4. Since docfx_project\_site is empty until I run the generator, it contains no .gitignore file, which has the effect of making everything in the junction directory, docs visible to Git.

5. Update my local Git repository, then push everything to GitHub.

6. On GitHub, configure GitHub Pages to point to the /docs subdirectory.

Presto! We have GitHub Pages generated entirely by DocFX.

There is one deviation from a stock DocFX installation; my API documentation uses a custom template that overrides the Bootstrap styles applied to the navigation bar and the H1 and H2 tags.

[txwizard]

Today, I published an article that describes in detail how I integrated DocFX with GitHub Pages. See https://www.codeproject.com/Articles/1260150/How-To-Integrate-DocFX-API-Documentation-Into-Your.

[Mogikan]

This is all great, but should be supported out of the box without 10 pages of workarounds.

[AlexHedley]

Article explaining how to use GitHub Actions to deploy to GH pages:

Conceptual and API documentation with Docfx, Github Actions and Github Pages

[AlexHedley]

Creating a site for your project using DocFX from @kblok

[tbebekis]

GitHub pages looks for a /docs as the publishing source.

So to make DocFx place its output to a /docs folder under the root project folder, just set the build "dest" property to "../docs" and then use the docfx command, in order to generate metadata and build the site at once.

Here is my folder structure. I have two projects, a WinForms and a Library. DocFx is the docfx_project folder.

    + App
    + DocFx
    + Lib
    Solution.sln

Here is my docfx.json. _ref is the api folder. The Overview folder contains conceptual documentation files.

{
    "metadata": [
        {
            "src": [
                {
            "files": [ "**/**.csproj" ],
            "src": ".."
                }
            ],
            "dest": "_ref",
            "disableGitFeatures": false,
            "disableDefaultFilter": false,
            "filter": "filterConfig.yml"
        }
    ],
    "build": {
        "content": [
            {
                "files": [
                    "_ref/**.yml",
                    "_ref/index.md"
                ]
            },
            {
                "files": [
                    "Overview/toc.yml",
                    "Overview/**.md",
                    "Overview/**/toc.yml",
                    "toc.yml",
                    "*.md"
                ]
            }
        ],
        "resource": [
            {
                "files": [ "images/**" ]
            }
        ],
        "dest": "../docs",
        "globalMetadataFiles": [],
        "fileMetadataFiles": [],
        "template": [ "default" ],
        "postProcessors": [],
        "markdownEngineName": "markdig",
        "noLangKeyword": false,
        "keepFileLink": false,
        "cleanupCacheHistory": false,
        "disableGitFeatures": false
    }
}

...and then open a terminal cd to C:\Solution\DocFx and then

cd C:\Solution\DocFx
docfx
cd ..\docs
docfx serve -p 8081

You may add docs folder to local git repository, commit and push to github.

[txwizard]

Thanks you very much, @tbebekis, for your succinct, but well illustrated example of a simpler configuration for automatic publication of DocFX API documentation as GitHub pages. I think it's time to mark this issue as closed. What say you, @olegburov?

[AlexHedley]

I recently managed to automate this with GitHub Actions

Check the “args” and “publish_dir” and modify given your repo structure/layout.
You may want it in different triggers too:

name: github pages

on:
  push:
    branches:
      - dev

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: docfx-action
        uses: nikeee/[email protected]
        with:
          args: docs/docfx.json

      - name: Deploy
        uses: peaceiris/[email protected]
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_site

Updated example to 1.0.0:
https://github.com/nikeee/docfx-action

[AlexHedley]

@txwizard do you not think it would be nice to have this baked into the platform much like the original Jekyll GHP deployments so you don’t need to run GHAs (ADO pipelines, etc), or even manually like @tbebekis has documented?

[txwizard]

@tbebekis, I owe you a very belated thanks for your simple alteration of docfx.json that made publishing to GitHub pages very straightforward.

@AlexHedley, I'm not sure how it could be made any simpler, unless perhaps by baking the destination for GitHub Pages into the default docfx.json that ships with the package. IMO, that would be a good idea anyway because it puts the documentation in a prominent location in its own directory off the main solution root.

[Mogikan]

Change
uses: nikeee/[email protected]
to
uses: nikeee/[email protected]

In case you use custom domain:

Add CNAME file to your repository. With yourdomain text.
Open docfx.json
Add to it:
"build": {
...
"resource": [
...
"files": [
...
"CNAME"

Otherwise CNAME file will be deleted each delpoy.