Tools for speeding up development of sites using docfx.
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
docfx-dev as a development dependency using
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
Build.Engine packages. A sparse, shallow checkout of the
src/docfx.website.themes folder will also be performed.
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 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
startcommands with your existing "develop" tasks to provide an almost seamless experience for template developers. They'll only need to run the
disabletask when they're done with content template development.
Update the version of docfx referenced by this package by performing the following steps:
docfx-commpon.ps1, change the
$docfxTagto the desired version. List of tags can be found here.
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.
lib/render.js, update the
To publish a new version of this package to npm:
versionproperty in the
Execute the following command:
- npm dependencies are in
- nuget dependencies are in
docfx-common.ps1does a sparse, shallow checkout of docfx's
src/docfx.website.themesfolder. These files are required to render content templates.
- source code is in the
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
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.