This repo is used to migrate docset from V2 to V3.
Last updated a year ago by docfx-migration-tool .
Repository · Original npm · Tarball · package.json
$ cnpm install @docfx-migration-tool/docs-docfx-migrationtool 
SYNC missed versions from official npm registry.


This repo is used to migrate existing V2 docset to V3.


  • install nodejs
  • run npm install in the repo to install npm packages

Prepare local doc repo for migration

Use git clone {gitRepoUrl} to clone the repo for migration, the following files are used during migration:

  • .openpublishing.publish.config.json
  • docfx.json
  • .openpublishing.redirection.json (if presents)

Migrate script usage

Run npm rum migrate -- -r {gitRepoUrl} -t {op-build-user-token} [-d {directory}] [-o {output-directory}] [-b {branch}] [-e {env}] [-l {log-path}]

  • {gitRepoUrl}: The git repository url(it should be https) e.g. https://github.com/MicrosoftDocs/azure-docs-pr (required)
  • {op-build-user-token}: Token used for invoking OPS APIs. Check hereto get a long period op build token for api request (required)
  • {directory}: The local git worktree directory(optional, will use current directory if not specified).
  • {output-directory}: Output directory for the generated docfx.yml, it will be the same as {directory} if it's not set.
  • {branch}: The git branch to migrate(optional)
  • {log-path}: The path of the log file(optional) (will only log to console if it's set to console-only)
  • {env}: The repository environment, can be prod, sandbox(default), internal or perf(optional)
  • {base-url}: 'The base url(https://{domain}/) of the publishing target')
  • {user-cache}: Add git-hub config property to config
  • {scan-redirection}: 'Scan all .md files' metadata and resolve redirections(attention, this is not optimized and may cause long running time)'

Check Migration Result

  • A docfx.yml will be generated inside the {output-directory}
  • Necessary changes will be made in the worktree(TBD)

Project Structure

The general idea is:

  1. load a default docfx.yml template
  2. load necessary configurations from from OPS server & local, including
    • .openpublishing.publish.config.json
    • docfx.json configs
    • .openpublishing.redirection.json
  3. calculate and fill in each property properly (and only support single docset case)

Running Test

The test framework used isMocha. Run npm test or npm t to run all the tests. Run with addition -- -w/--watch to run it in watch mode

Other utilities

Migrate usercache format: migrate user-cache file from old json format to new json format

  • usage: npm run migrate-usercache -- -i {inputFilePath} -o {outputFilePath}
  • example: npm run migrate-usercache -- -i d:\temp\input.json -o d:\temp\output.json

Development Guide

The main developing branch is dev for now, all package(npm, nuget) are generated from this branch.

Current Tags

87 Versions

Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 88
Dependencies (9)
Dev Dependencies (2)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |