Add option to disable normalization of spec download URLs (#402)

* first pass: hard-code false value for absolute

* WIP add toggle for absolute

* move URL normalization flag down to spec options

* undo package.json change

* docs(changeset): Add support for relative spec download URLs

* Apply suggestions from code review

* Update packages/docusaurus-theme-redoc/src/utils/useSpec.ts

---------

Co-authored-by: Rohit Gohri <[email protected]>

Author: ctreatma

.changeset/angry-doors-switch.md

@@ -0,0 +1,6 @@
+---
+'docusaurus-plugin-redoc': patch
+'docusaurus-theme-redoc': patch
+---
+
+Add support for relative spec download URLs

packages/docusaurus-plugin-redoc/src/index.ts

@@ -42,7 +42,7 @@ export default function redocPlugin(
 }> {
   const { baseUrl } = context.siteConfig;
   const options: PluginOptionsWithDefault = { ...DEFAULT_OPTIONS, ...opts };
-  const { debug, spec, url: downloadUrl, config, themeId } = options;
+  const { debug, spec, url: downloadUrl, config, themeId, normalizeUrl: normalizeDownloadUrl } = options;
 
   let url = downloadUrl;
   const isSpecFile = fs.existsSync(spec);
@@ -127,6 +127,7 @@ export default function redocPlugin(
         url,
         themeId,
         isSpecFile,
+        normalizeUrl: normalizeDownloadUrl,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         spec: content.converted as any,
       };

packages/docusaurus-plugin-redoc/src/options.ts

@@ -35,6 +35,7 @@ export interface PluginOptions extends PluginDirectUsageOptions {
   spec: string;
   url?: string;
   route?: string;
+  normalizeUrl?: boolean;
 }
 
 export interface PluginOptionsWithDefault extends PluginOptions {
@@ -44,6 +45,7 @@ export interface PluginOptionsWithDefault extends PluginOptions {
 export const DEFAULT_OPTIONS = {
   layout: {},
   debug: false,
+  normalizeUrl: true,
 } satisfies Omit<PluginOptions, 'spec'>;
 
 export const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -56,6 +58,7 @@ export const PluginOptionSchema = Joi.object<PluginOptions>({
   // Basic
   spec: Joi.string(),
   url: Joi.string().uri({ allowRelative: true }).optional(),
+  normalizeUrl: Joi.boolean().default(DEFAULT_OPTIONS.normalizeUrl),
   route: Joi.string().uri({ relativeOnly: true }).optional(),
   layout: Joi.any().default(DEFAULT_OPTIONS.layout),
 });

packages/docusaurus-theme-redoc/src/redocData.ts

@@ -30,7 +30,7 @@ const getDefaultTheme = (
         prism: {
           additionalLanguages: ['scala'],
         },
-      },
+      }
     },
     customTheme,
   );
@@ -148,6 +148,7 @@ export function getRedocThemes(
 export async function getGlobalData({
   primaryColor,
   primaryColorDark = primaryColor,
+  //normalizeUrl = true,
   theme: customThemeDeprecated,
   options,
 }: ThemeOptions): Promise<GlobalData> {

packages/docusaurus-theme-redoc/src/theme/Redoc/ServerStyles.tsx

@@ -40,7 +40,8 @@ export function ServerStyles({
   lightThemeOptions: RedocRawOptions;
   darkThemeOptions: RedocRawOptions;
 }) {
-  const fullUrl = useBaseUrl(specProps.url, { absolute: true });
+  const absoluteUrl = useBaseUrl(specProps.url, { absolute: true });
+  const fullUrl = specProps.normalizeUrl ? absoluteUrl : specProps.url;
 
   const lightCss = prefixCssSelectors(
     renderCss(new AppStore(specProps.spec, fullUrl, lightThemeOptions)),

packages/docusaurus-theme-redoc/src/types/common.ts

@@ -9,6 +9,7 @@ export interface SpecProps {
   url?: string;
   isSpecFile?: boolean;
   themeId?: string;
+  normalizeUrl?: boolean;
 }
 
 export type RedocProps = SpecProps;

packages/docusaurus-theme-redoc/src/types/modules.ts

@@ -4,6 +4,7 @@ interface SpecProps {
   url?: string;
   isSpecFile?: boolean;
   themeId?: string;
+  normalizeUrl?: boolean;
 }
 
 declare module '@theme/Redoc' {

packages/docusaurus-theme-redoc/src/utils/useSpec.ts

@@ -17,11 +17,12 @@ let currentStore: AppStore | null = null;
  * Released under the MIT License
  */
 export function useSpec(
-  { spec, url, themeId }: SpecProps,
+  { spec, url, themeId, normalizeUrl }: SpecProps,
   optionsOverrides?: RedocRawOptions,
 ) {
   const specOptions = useSpecOptions(themeId, optionsOverrides);
-  const fullUrl = useBaseUrl(url, { absolute: true });
+  const absoluteUrl = useBaseUrl(url, { absolute: true });
+  const fullUrl = normalizeUrl ? absoluteUrl : url;
   const isBrowser = useIsBrowser();
   const isDarkTheme = useColorMode().colorMode === 'dark';