Add option for relative symlinks

citkane · Aug 19, 2023 · 705dabc · 705dabc
1 parent 419168e
commit 705dabc
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+| :warning: DEPRECATION WARNING                                                |
+| :--------------------------------------------------------------------------- |
+| This package will not work with Typedoc > v0.23 due to breaking API changes. |
+
 [![RELEASE AND PUBLISH](https://github.com/citkane/typedoc-plugin-versions/actions/workflows/release.yml/badge.svg)](https://github.com/citkane/typedoc-plugin-versions/actions/workflows/release.yml)
 [![codecov](https://codecov.io/gh/citkane/typedoc-plugin-versions/branch/main/graph/badge.svg?token=5DDL83JO0R)](https://codecov.io/gh/citkane/typedoc-plugin-versions)
 [![GitHub](https://badgen.net/badge/icon/github?icon=github&label)](https://github.com/citkane/typedoc-plugin-versions)
@@ -33,12 +37,13 @@ and then set up your environment in typedoc.json
 
 ## Options
 
-| Key               | Value Information                                                                                                         | Type     | Required | Default                                                                                                                                                                              |
-| :---------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **_stable_**      | The version that you would like to be marked as `stable`                                                                  | `string` |  **no**  | [Automatically inferred](https://github.com/citkane/typedoc-plugin-versions/wiki/%22stable%22-and-%22dev%22-version-automatic-inference) based on current version and build history. |
-| **_dev_**         | The version that you would like to be marked as `dev`                                                                     | `string` |  **no**  | [Automatically inferred](https://github.com/citkane/typedoc-plugin-versions/wiki/%22stable%22-and-%22dev%22-version-automatic-inference) based on current version and build history. |
-| **_domLocation_** | A custom DOM location to render the HTML `select` dropdown corresponding to typedoc rendererHooks, eg. "navigation.begin" | `string` |  **no**  | Injects to left of header using vanilla js - not a typedoc render hook.                                                                                                              |
-| **rootFile**         | Optionally pass in the name of the rootFile to refer to for versions.json                                                                     | `string` |  **no**  | package.json | 
+| Key                   | Value Information                                                                                                         | Type      | Required | Default                                                                                                                                                                              |
+| :-------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **_stable_**          | The version that you would like to be marked as `stable`                                                                  | `string`  |  **no**  | [Automatically inferred](https://github.com/citkane/typedoc-plugin-versions/wiki/%22stable%22-and-%22dev%22-version-automatic-inference) based on current version and build history. |
+| **_dev_**             | The version that you would like to be marked as `dev`                                                                     | `string`  |  **no**  | [Automatically inferred](https://github.com/citkane/typedoc-plugin-versions/wiki/%22stable%22-and-%22dev%22-version-automatic-inference) based on current version and build history. |
+| **_domLocation_**     | A custom DOM location to render the HTML `select` dropdown corresponding to typedoc rendererHooks, eg. "navigation.begin" | `string`  |  **no**  | Injects to left of header using vanilla js - not a typedoc render hook.                                                                                                              |
+| **packageFile**       | Pass in an alternative name convention for "package.json"                                                                 | `string`  |  **no**  | package.json                                                                                                                                                                         |
+| **makeRelativeLinks** | Create relative instead of absolute symlinks in the document out directory                                                | `boolean` |  **no**  | `false`                                                                                                                                                                              |
 
 <br /><br />
 

diff --git a/package.json b/package.json
@@ -1,13 +1,13 @@
 {
 	"name": "typedoc-plugin-versions",
-	"version": "0.2.3",
+	"version": "0.2.4",
 	"description": "It keeps track of your document builds and provides a select menu for versions",
 	"main": "src/index",
 	"scripts": {
 		"test": "prettier -c . && nyc mocha",
 		"build": "npx tsc && node ./build.js",
 		"docs": "typedoc",
-    "docs:build": "npm run build && typedoc"
+		"docs:build": "npm run build && typedoc"
 	},
 	"repository": {
 		"type": "git",

diff --git a/src/etc/utils.ts b/src/etc/utils.ts
@@ -47,7 +47,7 @@ export function refreshMetadata(
 	docRoot: string,
 	stable = 'auto',
 	dev = 'auto',
-	rootFile = 'package.json'
+	packageFile = 'package.json'
 ): metadata {
 	const validate = (v: string) => (v === 'auto' ? v : getSemanticVersion(v));
 	const vStable = validate(stable);
@@ -56,7 +56,7 @@ export function refreshMetadata(
 	const versions = refreshMetadataVersions(
 		[...(metadata.versions ?? []), metadata.stable, metadata.dev],
 		docRoot,
-		rootFile
+		packageFile
 	);
 
 	return {
@@ -75,7 +75,7 @@ export function refreshMetadata(
 export function refreshMetadataVersions(
 	versions: version[],
 	docRoot: string,
-	rootFile
+	packageFile
 ) {
 	return (
 		[
@@ -101,7 +101,7 @@ export function refreshMetadataVersions(
 			...getVersions(getPackageDirectories(docRoot)),
 
 			// package.json version
-			getSemanticVersion(getPackageVersion(rootFile)),
+			getSemanticVersion(getPackageVersion(packageFile)),
 
 			// stable and dev symlinks
 			getSymlinkVersion('stable', docRoot),
@@ -301,14 +301,19 @@ export function makeJsKeys(metadata: metadata): string {
 export function makeAliasLink(
 	alias: semanticAlias,
 	docRoot: string,
-	pegVersion: version
+	pegVersion: version,
+	makeRelativeSymlinks?: boolean
 ): void {
 	pegVersion = getSemanticVersion(pegVersion);
-	const stableSource = path.join(docRoot, pegVersion);
+	const _docRoot = makeRelativeSymlinks ? './' : docRoot;
+	const stableSource = path.join(_docRoot, pegVersion);
+	const stableTarget = path.join(_docRoot, alias);
+
+	if (makeRelativeSymlinks) process.chdir(docRoot);
 
 	if (!fs.pathExistsSync(stableSource))
 		throw new Error(`Document directory does not exist: ${pegVersion}`);
-	const stableTarget = path.join(docRoot, alias);
+
 	if (fs.lstatSync(stableTarget, { throwIfNoEntry: false })?.isSymbolicLink())
 		fs.unlinkSync(stableTarget);
 	fs.ensureSymlinkSync(stableSource, stableTarget, 'junction');
@@ -322,6 +327,7 @@ export function makeAliasLink(
 export function makeMinorVersionLinks(
 	versions: version[],
 	docRoot: string,
+	makeRelativeSymlinks?: boolean,
 	stable: 'auto' | version = 'auto',
 	dev: 'auto' | version = 'auto'
 ): void {
@@ -352,8 +358,11 @@ export function makeMinorVersionLinks(
 		})
 		// filter to unique values
 		.filter((v, i, s) => s.indexOf(v) === i)) {
-		const target = path.join(docRoot, getMinorVersion(version));
-		const src = path.join(docRoot, version);
+		const _docRoot = makeRelativeSymlinks ? './' : docRoot;
+		const target = path.join(_docRoot, getMinorVersion(version));
+		const src = path.join(_docRoot, version);
+		if (makeRelativeSymlinks) process.chdir(docRoot);
+
 		if (fs.lstatSync(target, { throwIfNoEntry: false })?.isSymbolicLink())
 			fs.unlinkSync(target);
 		fs.ensureSymlinkSync(src, target, 'junction');
@@ -445,8 +454,8 @@ export const verRegex = /^(v\d+|\d+).\d+.\d+/;
  */
 export const minorVerRegex = /^(v\d+|\d+).\d+$/;
 
-function getPackageVersion(rootFile: string) {
-	const packagePath = path.join(process.cwd(), rootFile);
+function getPackageVersion(packageFile: string) {
+	const packagePath = path.join(process.cwd(), packageFile);
 	const pack = fs.readJSONSync(packagePath);
 	return pack.version;
 }
diff --git a/src/index.ts b/src/index.ts
@@ -26,14 +26,10 @@ export function load(app: Application) {
 			stable: 'auto',
 			dev: 'auto',
 			domLocation: 'false',
+			packageFile: 'package.json',
+			makeRelativeLinks: false,
 		} as versionsOptions,
 	});
-	app.options.addDeclaration({
-		help: 'Root file',
-		name: 'rootFile',
-		type: ParameterType.String,
-		defaultValue: 'package.json',
-	});
 
 	const vOptions = vUtils.getVersionsOptions(app) as versionsOptions;
 
@@ -65,16 +61,26 @@ export function load(app: Application) {
 			rootPath,
 			vOptions.stable,
 			vOptions.dev,
-			vOptions.rootFile
+			vOptions.packageFile
 		);
 
 		vUtils.makeAliasLink(
 			'stable',
 			rootPath,
-			metadata.stable ?? metadata.dev
+			metadata.stable ?? metadata.dev,
+			vOptions.makeRelativeLinks
+		);
+		vUtils.makeAliasLink(
+			'dev',
+			rootPath,
+			metadata.dev ?? metadata.stable,
+			vOptions.makeRelativeLinks
+		);
+		vUtils.makeMinorVersionLinks(
+			metadata.versions,
+			rootPath,
+			vOptions.makeRelativeLinks
 		);
-		vUtils.makeAliasLink('dev', rootPath, metadata.dev ?? metadata.stable);
-		vUtils.makeMinorVersionLinks(metadata.versions, rootPath);
 
 		const jsVersionKeys = vUtils.makeJsKeys(metadata);
 		fs.writeFileSync(path.join(rootPath, 'versions.js'), jsVersionKeys);

diff --git a/src/types.ts b/src/types.ts
@@ -23,7 +23,8 @@ export interface versionsOptions {
 	 * Default: Injects to left of header using vanilla js - not a typedoc render hook.
 	 */
 	domLocation?: validLocation | 'false';
-	rootFile?: string | 'package.json';
+	packageFile?: string | 'package.json';
+	makeRelativeLinks?: boolean;
 }
 export type version = `v${string}`;
 

diff --git a/test/stubs/stubs.ts b/test/stubs/stubs.ts
@@ -5,7 +5,13 @@ export const stubsPath = __dirname;
 export const docsPath = path.join(stubsPath, 'docs');
 export const stubVersions = ['v0.0.0', 'v0.1.0', 'v0.1.1', 'v0.2.3', 'v0.10.1'];
 export const stubSemanticLinks = ['v0.0', 'v0.1', 'v0.2', 'v0.10'];
-export const stubOptionKeys = ['stable', 'dev', 'domLocation'];
+export const stubOptionKeys = [
+	'stable',
+	'dev',
+	'domLocation',
+	'packageFile',
+	'makeRelativeLinks',
+];
 export const stubPathKeys = ['rootPath', 'targetPath'];
 export const stubRootPath =
 	process.platform === 'win32' ? '\\test\\stubs\\docs' : '/test/stubs/docs';

diff --git a/typedoc.json b/typedoc.json
@@ -7,5 +7,6 @@
 	"externalPattern": ["**/node_modules/**"],
 	"excludeExternals": true,
 	"logLevel": "Verbose",
-	"plugin": ["./dist"]
+	"plugin": ["./dist"],
+	"versions": { "packageFile": "package.json", "makeRelativeLinks": false }
 }