@docusaurus/utils 0.0.0-4759 → 0.0.0-4762

package/src/tags.ts

@@ -10,12 +10,13 @@ import {normalizeUrl} from './urlUtils';
 
 export type Tag = {
   label: string;
+  /** Permalink to this tag's page, without the `/tags/` base path. */
   permalink: string;
 };
 
 export type FrontMatterTag = string | Tag;
 
-export function normalizeFrontMatterTag(
+function normalizeFrontMatterTag(
   tagsPath: string,
   frontMatterTag: FrontMatterTag,
 ): Tag {
@@ -45,8 +46,19 @@ export function normalizeFrontMatterTag(
   };
 }
 
+/**
+ * Takes tag objects as they are defined in front matter, and normalizes each
+ * into a standard tag object. The permalink is created by appending the
+ * sluggified label to `tagsPath`. Front matter tags already containing
+ * permalinks would still have `tagsPath` prepended.
+ *
+ * The result will always be unique by permalinks. The behavior with colliding
+ * permalinks is undetermined.
+ */
 export function normalizeFrontMatterTags(
+  /** Base path to append the tag permalinks to. */
   tagsPath: string,
+  /** Can be `undefined`, so that we can directly pipe in `frontMatter.tags`. */
   frontMatterTags: FrontMatterTag[] | undefined = [],
 ): Tag[] {
   const tags = frontMatterTags.map((tag) =>
@@ -56,42 +68,42 @@ export function normalizeFrontMatterTags(
   return _.uniqBy(tags, (tag) => tag.permalink);
 }
 
-export type TaggedItemGroup<Item> = {
+type TaggedItemGroup<Item> = {
   tag: Tag;
   items: Item[];
 };
 
 /**
- * Permits to group docs/blogPosts by tag (provided by front matter)
- * Note: groups are indexed by permalink, because routes must be unique in the
- * end. Labels may vary on 2 md files but they are normalized. Docs with
- * label='some label' and label='some-label' should end-up in the same
- * group/page in the end. We can't create 2 routes /some-label because one would
- * override the other
+ * Permits to group docs/blog posts by tag (provided by front matter).
+ *
+ * @returns a map from tag permalink to the items and other relevant tag data.
+ * The record is indexed by permalink, because routes must be unique in the end.
+ * Labels may vary on 2 MD files but they are normalized. Docs with
+ * label='some label' and label='some-label' should end up in the same page.
  */
 export function groupTaggedItems<Item>(
   items: readonly Item[],
+  /**
+   * A callback telling me how to get the tags list of the current item. Usually
+   * simply getting it from some metadata of the current item.
+   */
   getItemTags: (item: Item) => readonly Tag[],
-): Record<string, TaggedItemGroup<Item>> {
-  const result: Record<string, TaggedItemGroup<Item>> = {};
-
-  function handleItemTag(item: Item, tag: Tag) {
-    // Init missing tag groups
-    // TODO: it's not really clear what should be the behavior if 2 items have
-    // the same tag but the permalink is different for each
-    // For now, the first tag found wins
-    result[tag.permalink] ??= {
-      tag,
-      items: [],
-    };
-
-    // Add item to group
-    result[tag.permalink]!.items.push(item);
-  }
+): {[permalink: string]: TaggedItemGroup<Item>} {
+  const result: {[permalink: string]: TaggedItemGroup<Item>} = {};
 
   items.forEach((item) => {
     getItemTags(item).forEach((tag) => {
-      handleItemTag(item, tag);
+      // Init missing tag groups
+      // TODO: it's not really clear what should be the behavior if 2 tags have
+      // the same permalink but the label is different for each
+      // For now, the first tag found wins
+      result[tag.permalink] ??= {
+        tag,
+        items: [],
+      };
+
+      // Add item to group
+      result[tag.permalink]!.items.push(item);
     });
   });
 

package/src/urlUtils.ts

@@ -8,6 +8,18 @@
 import {removeSuffix} from './jsUtils';
 import resolvePathnameUnsafe from 'resolve-pathname';
 
+/**
+ * Much like `path.join`, but much better. Takes an array of URL segments, and
+ * joins them into a reasonable URL.
+ *
+ * - `["file:", "/home", "/user/", "website"]` => `file:///home/user/website`
+ * - `["file://", "home", "/user/", "website"]` => `file://home/user/website` (relative!)
+ * - Remove trailing slash before parameters or hash.
+ * - Replace `?` in query parameters with `&`.
+ * - Dedupe forward slashes in the entire path, avoiding protocol slashes.
+ *
+ * @throws {TypeError} If any of the URL segment is not a string, this throws.
+ */
 export function normalizeUrl(rawUrls: string[]): string {
   const urls = [...rawUrls];
   const resultArray = [];
@@ -75,8 +87,8 @@ export function normalizeUrl(rawUrls: string[]): string {
   }
 
   let str = resultArray.join('/');
-  // Each input component is now separated by a single slash
-  // except the possible first plain protocol part.
+  // Each input component is now separated by a single slash except the possible
+  // first plain protocol part.
 
   // Remove trailing slash before parameters or hash.
   str = str.replace(/\/(?<search>\?|&|#[^!])/g, '$1');
@@ -94,6 +106,11 @@ export function normalizeUrl(rawUrls: string[]): string {
   return str;
 }
 
+/**
+ * Takes a file's path, relative to its content folder, and computes its edit
+ * URL. If `editUrl` is `undefined`, this returns `undefined`, as is the case
+ * when the user doesn't want an edit URL in her config.
+ */
 export function getEditUrl(
   fileRelativePath: string,
   editUrl?: string,
@@ -105,8 +122,8 @@ export function getEditUrl(
 }
 
 /**
- * Convert filepath to url path.
- * Example: 'index.md' -> '/', 'foo/bar.js' -> '/foo/bar',
+ * Converts file path to a reasonable URL path, e.g. `'index.md'` -> `'/'`,
+ * `'foo/bar.js'` -> `'/foo/bar'`
  */
 export function fileToPath(file: string): string {
   const indexRE = /(?<dirname>^|.*\/)index\.(?:mdx?|jsx?|tsx?)$/i;
@@ -118,6 +135,13 @@ export function fileToPath(file: string): string {
   return `/${file.replace(extRE, '').replace(/\\/g, '/')}`;
 }
 
+/**
+ * Similar to `encodeURI`, but uses `encodeURIComponent` and assumes there's no
+ * query.
+ *
+ * `encodeURI("/question?/answer")` => `"/question?/answer#section"`;
+ * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23foo"`
+ */
 export function encodePath(userPath: string): string {
   return userPath
     .split('/')
@@ -125,6 +149,10 @@ export function encodePath(userPath: string): string {
     .join('/');
 }
 
+/**
+ * Whether `str` is a valid pathname. It must be absolute, and not contain
+ * special characters.
+ */
 export function isValidPathname(str: string): boolean {
   if (!str.startsWith('/')) {
     return false;
@@ -138,22 +166,31 @@ export function isValidPathname(str: string): boolean {
   }
 }
 
-// resolve pathname and fail fast if resolution fails
+/**
+ * Resolve pathnames and fail-fast if resolution fails. Uses standard URL
+ * semantics (provided by `resolve-pathname` which is used internally by React
+ * router)
+ */
 export function resolvePathname(to: string, from?: string): string {
   return resolvePathnameUnsafe(to, from);
 }
+/** Appends a leading slash to `str`, if one doesn't exist. */
 export function addLeadingSlash(str: string): string {
   return str.startsWith('/') ? str : `/${str}`;
 }
 
 // TODO deduplicate: also present in @docusaurus/utils-common
+/** Appends a trailing slash to `str`, if one doesn't exist. */
 export function addTrailingSlash(str: string): string {
   return str.endsWith('/') ? str : `${str}/`;
 }
+
+/** Removes the trailing slash from `str`. */
 export function removeTrailingSlash(str: string): string {
   return removeSuffix(str, '/');
 }
 
+/** Constructs an SSH URL that can be used to push to GitHub. */
 export function buildSshUrl(
   githubHost: string,
   organizationName: string,
@@ -166,6 +203,7 @@ export function buildSshUrl(
   return `git@${githubHost}:${organizationName}/${projectName}.git`;
 }
 
+/** Constructs an HTTP URL that can be used to push to GitHub. */
 export function buildHttpsUrl(
   gitCredentials: string,
   githubHost: string,
@@ -179,6 +217,11 @@ export function buildHttpsUrl(
   return `https://${gitCredentials}@${githubHost}/${organizationName}/${projectName}.git`;
 }
 
+/**
+ * Whether the current URL is an SSH protocol. In addition to looking for
+ * `ssh:`, it will also allow protocol-less URLs like
+ * `git@github.com:facebook/docusaurus.git`.
+ */
 export function hasSSHProtocol(sourceRepoUrl: string): boolean {
   try {
     if (new URL(sourceRepoUrl).protocol === 'ssh:') {
@@ -187,6 +230,6 @@ export function hasSSHProtocol(sourceRepoUrl: string): boolean {
     return false;
   } catch {
     // Fails when there isn't a protocol
-    return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl); // git@github.com:facebook/docusaurus.git
+    return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl);
   }
 }

package/src/webpackUtils.ts

@@ -31,7 +31,11 @@ type FileLoaderUtils = {
   };
 };
 
-// Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+/**
+ * Returns unified loader configurations to be used for various file types.
+ *
+ * Inspired by https://github.com/gatsbyjs/gatsby/blob/8e6e021014da310b9cc7d02e58c9b3efe938c665/packages/gatsby/src/utils/webpack-utils.ts#L447
+ */
 export function getFileLoaderUtils(): FileLoaderUtils {
   // files/images < urlLoaderLimit will be inlined as base64 strings directly in
   // the html
@@ -39,7 +43,11 @@ export function getFileLoaderUtils(): FileLoaderUtils {
 
   // defines the path/pattern of the assets handled by webpack
   const fileLoaderFileName = (folder: AssetFolder) =>
-    `${OUTPUT_STATIC_ASSETS_DIR_NAME}/${folder}/[name]-[contenthash].[ext]`;
+    path.posix.join(
+      OUTPUT_STATIC_ASSETS_DIR_NAME,
+      folder,
+      '[name]-[contenthash].[ext]',
+    );
 
   const loaders: FileLoaderUtils['loaders'] = {
     file: (options: {folder: AssetFolder}) => ({