@docusaurus/utils 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

package/src/normalizeUrl.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export function normalizeUrl(rawUrls: string[]): string {
+  const urls = [...rawUrls];
+  const resultArray = [];
+
+  let hasStartingSlash = false;
+  let hasEndingSlash = false;
+
+  // If the first part is a plain protocol, we combine it with the next part.
+  if (urls[0].match(/^[^/:]+:\/*$/) && urls.length > 1) {
+    const first = urls.shift();
+    urls[0] = first + urls[0];
+  }
+
+  // There must be two or three slashes in the file protocol,
+  // two slashes in anything else.
+  const replacement = urls[0].match(/^file:\/\/\//) ? '$1:///' : '$1://';
+  urls[0] = urls[0].replace(/^([^/:]+):\/*/, replacement);
+
+  // eslint-disable-next-line
+  for (let i = 0; i < urls.length; i++) {
+    let component = urls[i];
+
+    if (typeof component !== 'string') {
+      throw new TypeError(`Url must be a string. Received ${typeof component}`);
+    }
+
+    if (component === '') {
+      if (i === urls.length - 1 && hasEndingSlash) {
+        resultArray.push('/');
+      }
+      // eslint-disable-next-line
+      continue;
+    }
+
+    if (component !== '/') {
+      if (i > 0) {
+        // Removing the starting slashes for each component but the first.
+        component = component.replace(
+          /^[/]+/,
+          // Special case where the first element of rawUrls is empty ["", "/hello"] => /hello
+          component[0] === '/' && !hasStartingSlash ? '/' : '',
+        );
+      }
+
+      hasEndingSlash = component[component.length - 1] === '/';
+      // Removing the ending slashes for each component but the last.
+      // For the last component we will combine multiple slashes to a single one.
+      component = component.replace(/[/]+$/, i < urls.length - 1 ? '' : '/');
+    }
+
+    hasStartingSlash = true;
+    resultArray.push(component);
+  }
+
+  let str = resultArray.join('/');
+  // 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(/\/(\?|&|#[^!])/g, '$1');
+
+  // Replace ? in parameters with &.
+  const parts = str.split('?');
+  str = parts.shift() + (parts.length > 0 ? '?' : '') + parts.join('&');
+
+  // Dedupe forward slashes in the entire path, avoiding protocol slashes.
+  str = str.replace(/([^:]\/)\/+/g, '$1');
+
+  // Dedupe forward slashes at the beginning of the path.
+  str = str.replace(/^\/+/g, '/');
+
+  return str;
+}

package/src/tags.ts

@@ -0,0 +1,100 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {kebabCase, uniq, uniqBy} from 'lodash';
+import {normalizeUrl} from './normalizeUrl';
+
+export type Tag = {
+  label: string;
+  permalink: string;
+};
+
+export type FrontMatterTag = string | Tag;
+
+export function normalizeFrontMatterTag(
+  tagsPath: string,
+  frontMatterTag: FrontMatterTag,
+): Tag {
+  function toTagObject(tagString: string): Tag {
+    return {
+      label: tagString,
+      permalink: kebabCase(tagString),
+    };
+  }
+
+  // TODO maybe make ensure the permalink is valid url path?
+  function normalizeTagPermalink(permalink: string): string {
+    // note: we always apply tagsPath on purpose
+    // for versioned docs, v1/doc.md and v2/doc.md tags with custom permalinks don't lead to the same created page
+    // tagsPath is different for each doc version
+    return normalizeUrl([tagsPath, permalink]);
+  }
+
+  const tag: Tag =
+    typeof frontMatterTag === 'string'
+      ? toTagObject(frontMatterTag)
+      : frontMatterTag;
+
+  return {
+    label: tag.label,
+    permalink: normalizeTagPermalink(tag.permalink),
+  };
+}
+
+export function normalizeFrontMatterTags(
+  tagsPath: string,
+  frontMatterTags: FrontMatterTag[] | undefined,
+): Tag[] {
+  const tags =
+    frontMatterTags?.map((tag) => normalizeFrontMatterTag(tagsPath, tag)) ?? [];
+
+  return uniqBy(tags, (tag) => tag.permalink);
+}
+
+export type TaggedItemGroup<Item> = {
+  tag: Tag;
+  items: Item[];
+};
+
+// Permits to group docs/blogPosts by tag (provided by FrontMatter)
+// 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
+export function groupTaggedItems<Item>(
+  items: Item[],
+  getItemTags: (item: Item) => 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] = result[tag.permalink] ?? {
+      tag,
+      items: [],
+    };
+
+    // Add item to group
+    result[tag.permalink].items.push(item);
+  }
+
+  items.forEach((item) => {
+    getItemTags(item).forEach((tag) => {
+      handleItemTag(item, tag);
+    });
+  });
+
+  // If user add twice the same tag to a md doc (weird but possible),
+  // we don't want the item to appear twice in the list...
+  Object.values(result).forEach((group) => {
+    group.items = uniq(group.items);
+  });
+
+  return result;
+}

package/src/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare module 'resolve-pathname' {
+  export default function resolvePathname(to: string, from?: string): string;
+}