@docfx-migration-tool/docs-docfx-migrationtool v2.4.0

Introduction

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

Prerequisites

• 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.