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
andstart
commands with your existing "develop" tasks to provide an almost seamless experience for template developers. They'll only need to run thedisable
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:
-
In
docfx-commpon.ps1
, change the$docfxTag
to the desired version. List of tags can be found here. -
In
packages.config
, update the version of theMicrosoft.DocAsCode.*
packages. Confirm the package references for Jint, Nustache, Newtonsoft.Json and System.Collections.Immutable match the versions referenced by docfx. -
In
lib/render.js
, update thedocfxVersion
constant.
publishing
To publish a new version of this package to npm:
-
Increment the
version
property in thepackage.json
file. -
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'ssrc/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 theenable
/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.
-