URL and Web Utilities

/**
 * Represents a URL path with optional query and hash components
 */
type URLPath = {
  pathname: string;
  search?: string;
  hash?: string;
};

/**
 * Joins URL segments into a reasonable URL
 * @param rawUrls - Array of URL segments to join
 * @returns Normalized URL string
 * @throws TypeError if any segment is not a string
 */
function normalizeUrl(rawUrls: string[]): string;

import { normalizeUrl } from "@docusaurus/utils";

// Basic URL joining
const url1 = normalizeUrl(["https://example.com", "docs", "intro"]);
// Result: "https://example.com/docs/intro"

// Handle trailing/leading slashes
const url2 = normalizeUrl(["https://example.com/", "/docs/", "/intro/"]);
// Result: "https://example.com/docs/intro"

// Preserve protocols
const url3 = normalizeUrl(["mailto:user@example.com"]);
// Result: "mailto:user@example.com"

/**
 * Converts file path to URL path (e.g., 'index.md' → '/', 'foo/bar.js' → '/foo/bar')
 * @param file - File path to convert
 * @returns URL path string
 */
function fileToPath(file: string): string;

import { fileToPath } from "@docusaurus/utils";

// Index files become root paths
const indexPath = fileToPath("index.md");
// Result: "/"

const nestedIndex = fileToPath("docs/index.md");
// Result: "/docs/"

// Regular files lose extensions
const docPath = fileToPath("docs/introduction.md");
// Result: "/docs/introduction"

const jsPath = fileToPath("src/components/Button.js");
// Result: "/src/components/Button"

/**
 * Encodes path using encodeURIComponent for each segment
 * @param userPath - Path to encode
 * @returns Encoded path string
 */
function encodePath(userPath: string): string;

/**
 * Checks if string is a valid pathname
 * @param str - String to validate
 * @returns True if valid pathname
 */
function isValidPathname(str: string): boolean;

/**
 * Parses URL or path with optional base
 * @param url - URL or path string to parse
 * @param base - Optional base URL
 * @returns Parsed URL object
 * @throws Error with descriptive message on failure
 */
function parseURLOrPath(url: string, base?: string | URL): URL;

/**
 * Converts URL object to URLPath
 * @param url - URL object to convert
 * @returns URLPath with pathname, search, and hash
 */
function toURLPath(url: URL): URLPath;

/**
 * Parses URL path with optional base path
 * @param urlPath - URL path string to parse
 * @param fromPath - Optional base path for resolution
 * @returns Parsed URLPath object
 */
function parseURLPath(urlPath: string, fromPath?: string): URLPath;

/**
 * Parses local URL paths without resolving pathnames
 * @param urlPath - URL path to parse
 * @returns URLPath object or null for non-local URLs
 */
function parseLocalURLPath(urlPath: string): URLPath | null;

/**
 * Converts URLPath back to string representation
 * @param urlPath - URLPath object to serialize
 * @returns String representation of the URL path
 */
function serializeURLPath(urlPath: URLPath): string;

/**
 * Resolves pathnames using standard URL semantics
 * @param to - Target pathname
 * @param from - Base pathname for resolution
 * @returns Resolved pathname
 */
function resolvePathname(to: string, from?: string): string;

/**
 * Checks if URL uses SSH protocol
 * @param sourceRepoUrl - Repository URL to check
 * @returns True if SSH protocol is used
 */
function hasSSHProtocol(sourceRepoUrl: string): boolean;

/**
 * Constructs SSH URL for GitHub repository
 * @param githubHost - GitHub host (e.g., "github.com")
 * @param organizationName - GitHub organization or user name
 * @param projectName - Repository name
 * @param githubPort - Optional SSH port
 * @returns SSH URL string
 */
function buildSshUrl(
  githubHost: string,
  organizationName: string,
  projectName: string,
  githubPort?: string
): string;

/**
 * Constructs HTTPS URL for GitHub repository with credentials
 * @param gitCredentials - Git credentials string
 * @param githubHost - GitHub host
 * @param organizationName - Organization or user name
 * @param projectName - Repository name
 * @param githubPort - Optional HTTPS port
 * @returns HTTPS URL with credentials
 */
function buildHttpsUrl(
  gitCredentials: string,
  githubHost: string,
  organizationName: string,
  projectName: string,
  githubPort?: string
): string;

/**
 * Computes edit URL for a file
 * @param fileRelativePath - Relative path to the file
 * @param editUrl - Base edit URL template
 * @returns Edit URL string or undefined
 */
function getEditUrl(fileRelativePath: string, editUrl?: string): string | undefined;

import {
  encodePath,
  isValidPathname,
  parseURLPath,
  resolvePathname,
  hasSSHProtocol,
  getEditUrl,
} from "@docusaurus/utils";

// Encode path with special characters
const encoded = encodePath("/docs/guide with spaces/intro");
// Result: "/docs/guide%20with%20spaces/intro"

// Validate pathname
const isValid = isValidPathname("/docs/intro");
// Result: true

const isInvalid = isValidPathname("../../../etc/passwd");
// Result: false

// Parse URL paths
const parsed = parseURLPath("/docs/intro?version=1.0#installation");
// Result: { pathname: "/docs/intro", search: "?version=1.0", hash: "#installation" }

// Resolve relative paths
const resolved = resolvePathname("../guide/intro", "/docs/reference/");
// Result: "/docs/guide/intro"

// Check SSH protocol
const isSSH = hasSSHProtocol("git@github.com:facebook/docusaurus.git");
// Result: true

const isHTTPS = hasSSHProtocol("https://github.com/facebook/docusaurus.git");
// Result: false

// Generate edit URL
const editUrl = getEditUrl(
  "docs/intro.md",
  "https://github.com/facebook/docusaurus/edit/main/"
);
// Result: "https://github.com/facebook/docusaurus/edit/main/docs/intro.md"