docfx-dev

Tools for speeding up development of sites using docfx.

usage

docfx-dev is intended to be integrated with docfx site template development tasks via it's CLI interface. The primary goal is to speed up the development of templates and model transforms in the src/ContentTemplate/ folder.

Install docfx-dev as a development dependency using npm:

npm install --dev docfx-dev

docfx-dev uses the same packages and themes as docfx to render content templates. During the install docfx-dev will use nuget to download the docfx Common, Plugins and Build.Engine packages. A sparse, shallow checkout of the src/docfx.website.themes folder will also be performed.

Integrate docfx-dev into your development process by invoking the following command:

npm run docfx-dev enable

This will temporarily instrument your content templates (src/ContentTemplate/*.html.primary.(tmpl|js)) with three items:

• A JSON representation of the model, prior to any pre-processor transforms.
• The name of the content template (eg "ManagedReference")
• A client script that integrates with the docfx-dev http service.

Start the docfx-dev http service using the following command:

npm run docfx-dev start

The http service watches the content and content template files and pushes notifications via web-sockets to instrumented pages (like browser-sync). Once notified of a change the instrumented page will send a POST request containing it's url path, model and content template name to the http service, which will re-render the content template and update the file in the drop folder. This process ensures only the pages you have open in the browser will be re-rendered when you change a template. The overhead of regenerating the model is avoided, only the model preprocessor (Jint stuff) and the template render (Nustache stuff) are executed.

When you're done working on the content templates, execute the following command to remove the instrumentation code prior to check-in.

npm run docfx-dev disable

Tip: Integrate the enable and start commands with your existing "develop" tasks to provide an almost seamless experience for template developers. They'll only need to run the disable task when they're done with content template development.

updating docfx

Update the version of docfx referenced by this package by performing the following steps:

1. In docfx-commpon.ps1, change the $docfxTag to the desired version. List of tags can be found here.

2. In packages.config, update the version of the Microsoft.DocAsCode.* packages. Confirm the package references for Jint, Nustache, Newtonsoft.Json and System.Collections.Immutable match the versions referenced by docfx.

3. In lib/render.js, update the docfxVersion constant.

publishing

To publish a new version of this package to npm:

1. Increment the version property in the package.json file.

2. Execute the following command:

   npm publish

development notes

• npm dependencies are in package.json
• nuget dependencies are in packages.config
• docfx-common.ps1 does a sparse, shallow checkout of docfx's src/docfx.website.themes folder. These files are required to render content templates.
• source code is in the lib folder:
  • index.js: CLI entry point
  • client.js: client-side script loaded by instrumented pages. This runs in the browser.
  • instrument.js: logic to instrument *.primary.html.(js|tmpl) files. Invoked by the enable / disable commands.
  • render.js: uses the edge npm package to invoke the docfx template rendering libraries.
  • serve.js: the http server. Watches files, pushes notifications to instrumented pages, responds to requests to render content templates, serves the client.js script to pages.