Sibber.Docfx

This repo has the docfx config that I use for my library docs sites. It uses fuse.js in place of lunr.js, and the ExtractSearchIndexEx post processor which I forked from the docfx repo and modified to index all (configurable) public members of types in addition to the types themselves.

It also includes a Github Actions deployment workflow, which builds the docfx API metadata and site, and then configures GitHub Pages and deploys to it. See section in Usage for more details.

Usage

Important

Make sure build.postProcessors in docfx.json contains ExtractSearchIndex before ExtractSearchIndexEx.
ExtractSearchIndex cannot be disabled without disabling search, so ExtractSearchIndexEx assumes ExtractSearchIndex has already run and that index.json already exists as a resource in the manifest and overwrites it. If ExtractSearchIndex does not run before ExtractSearchIndexEx then the index.json generated by ExtractSearchIndexEx will be overwritten.

You can either create a 'docs' folder which contains only the files you want to override, and merge with the skeleton or manually copy 'docs' and configure.

Auto merge with skeleton

1. Create the docs folder in the root of you repo
2. Create a file named docfx.override.json in docs/. This contains the options that will override those in docfx.base.json
3. Add any other files that you want to add or overwrite ones in the skeleton with

Then you can use the deploynment workflow - with the USE SKELETON region uncommented - which, before building the documentation, will:

1. Clone the skeleton branch, which contains the (built) ExtractSearchIndexEx plugin
2. Override any options in docfx.base.json with the ones in docfx.override.json, if they exist there
3. Merge your docs directory with the skeleton's, overwriting any files in the skeleton with ones in your docs directory

Examples

Adding or overwriting files in the skeleton

If you add a `toc.yml` in `docs/` it will overwrite the `toc.yml` in the skeleton.\ if you add new files or folders that don't exist in the skeleton, they will just be added normally in the merged docs folder.

For example if you want to add an articles page, you just need to:

Create a toc.yml:

# This will overwrite the toc.yml in the skeleton
- name: Docs
  href: articles/
- name: API
  href: api/

Then create the articles folder in docs/, create a toc.yml inside it which contains the list of the names of the articles, and their hrefs which would be the name of the corresponding markdown file.

Overriding options in docfx.json

docfx.override.json:

{
   "$schema": "https://raw.githubusercontent.com/dotnet/docfx/main/schemas/docfx.schema.json",
   "build": {
      "globalMetadata": {
         "_appName": "myDifferentSite",
         "_appTitle": "myDifferentSite"
      }
   }
}

after being merged with docfx.base.json, will result in the following docfx.json:

... // same as docfx.base.json
-      "_appName": "mysite",
-      "_appTitle": "mysite",
+      "_appName": "myDifferentSite",
+      "_appTitle": "myDifferentSite",
... // same as docfx.main.json

Manual

1. Clone the repository
2. Run publish_plugins.bat
3. Copy the docs folder to your repository
4. Replace "mysite" in docs/docfx.json with site name
5. Fill in the urls in docs/templates/customizations/public/main.js
6. Add favicon.ico and icon.svg to docs/images/
7. [Optional] Configure fuse.js options in public/search-worker.min.js

Github Actions deployment workflow

To use the deployment workflow, change the following settings in your repository:

1. 'Pages' (under 'Code and automation') -> 'Build and deployment' source set to 'GitHub Actions'
2. [If using tag trigger] 'Environments' (under 'Code and automation') -> 'github-pages' -> under 'Deployment branches and tags' click 'Add deployment branch or tag rule' -> add v[0-9]* (fnmatch doesn't support more complex patterns)

It is triggered when a tag that matches v[0-9]+.[0-9]+* is pushed.
If you also only want to trigger when the tag is pushed to main (or a specific branch), the recommended approach is to set an environment protection rule (in the GitHub repo settings, under 'Environments/github-pages') to only allow deployments from the specific branch; However if this is not enough for your usecase then you can uncomment the condition for the build-documentation job, but make sure to read the warning there.

Note

If you are using auto merge with skeleton then uncomment the USE SKELETON region.
This will clone the skeleton branch and merge it with your docs folder which will merge the docfx.json file, and overwrite the other files in the skeleton with the one in docs.

Other defaults you may want to change:

• docfx[.override].json path: by default assumes it is in the docs/ folder in the root of your repo.
• .NET SDK version: by default uses 8.x, which is the minimum required by docfx.

ExtractSearchIndexEx

The ExtractSearchIndexEx post processor has 2 additional configuration options (set in globalMetadata in docfx.json):

• "_searchIndexStripSiteNameFromTitle": bool (default: false) specifies whether to remove the site name from the search result titels, e.g. Class SomeNamespace.SomeClass | SiteName becomes Class SomeNamespace.SomeClass. This only has an effect if _searchIndexUseMetadataTitle is set to false (or _searchIndexUseMetadata is false), or if the title metadata does not exist.
• "_searchIndexScopes": string[] (default: ["All"]) specifies what to be indexed. The possible values are the defined enum values in SearchScopes. e.g. ["Types", "Methods"]. ["Types"] would index the same symbols as the built in ExtractSearchIndex.

Notes

modern template

The modern template is just the normal docfx (compiled) modern template exported with docfx template export modern with the following changes:

• public/search-worker.min.js: replaced with fuse.js impl https://gist.github.com/filzrev/9a046c40f6df63d01f40018d8a19bd47 and modified
• public/search-worker.min.js.map: deleted
• public/docfx.min.js:
  • Line 17, removed +"?q="+It (search query from redirect url when clicking on a search result) so that fragment identifiers work
  • Line 15, removed let{lunrLanguages:e}=await D();i.postMessage({init:{lunrLanguages:e}});
  • Line 6, removed , "lunrLanguages"
• public/docfx.min.js.map:
  • Line 4, removed corresponding + '?q=' + query
  • Line 4, removed corresponsing const { lunrLanguages } = await options()\n worker.postMessage({ init: { lunrLanguages } })\n\n
• Deleted unused lunr files:
  • public/chunk-DTUU2GN4.min.js and public/chunk-DTUU2GN4.min.js.map (lunr japanese, not sure why its not named lunr.ja like the other localization files)
  • All files in public/ that being with lunr

License

The file ./ExtractSearchIndexEx/ExtractSearchIndexEx.cs was taken from Docfx.Build, github.com/dotnet/docfx, MIT License - Copyright (c) .NET Foundation and Contributors. See the license notice at the top of the file for more info.

The rest of the ExtractSearchIndexEx plugin and modifications to the file mentioned above are licensed under the MIT License - see LICENSE - unless otherwise stated in specific files or sections. See individual files for exceptions.

All files that are not in ExtractSearchIndexEx/ and not in docs/, and the files that are in docs/templates/customizations/, are licensed under the MIT License - see LICENSE - unless otherwise stated in specific files or sections.