File System & Path Operations

/**
 * Converts Windows backslash paths to posix forward slash paths
 * @param str - Path string to convert
 * @returns Path with forward slashes
 */
function posixPath(str: string): string;

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

const windowsPath = "C:\\Users\\docs\\file.md";
const convertedPath = posixPath(windowsPath);
// Result: "C:/Users/docs/file.md"

const alreadyPosix = "/home/user/docs/file.md";
const unchanged = posixPath(alreadyPosix);
// Result: "/home/user/docs/file.md"

/**
 * Creates @site-aliased path from absolute file path
 * @param filePath - Absolute file path
 * @param siteDir - Site root directory path
 * @returns @site-aliased path
 */
function aliasedSitePath(filePath: string, siteDir: string): string;

/**
 * Converts @site-aliased path back to relative path
 * @param filePath - @site-aliased file path
 * @returns Relative path
 */
function aliasedSitePathToRelativePath(filePath: string): string;

import { aliasedSitePath, aliasedSitePathToRelativePath } from "@docusaurus/utils";

// Create aliased path
const absolutePath = "/project/website/docs/intro.md";
const siteDir = "/project/website";
const aliased = aliasedSitePath(absolutePath, siteDir);
// Result: "@site/docs/intro.md"

// Convert back to relative
const relative = aliasedSitePathToRelativePath("@site/docs/intro.md");
// Result: "docs/intro.md"

/**
 * Checks if string exceeds filesystem path segment length limits
 * @param str - String to check
 * @returns True if name is too long for filesystem
 */
function isNameTooLong(str: string): boolean;

/**
 * Truncates string to fit within filesystem path segment limits
 * @param str - String to truncate
 * @returns Truncated string safe for filesystem
 */
function shortName(str: string): string;

/**
 * Adds platform-appropriate trailing path separator if not present
 * @param str - Path string
 * @returns Path with trailing separator
 */
function addTrailingPathSeparator(str: string): string;

/**
 * Escapes path for safe use in generated code
 * @param str - Path to escape
 * @returns Escaped path string
 */
function escapePath(str: string): string;

/**
 * Converts file path to relative posix path for user-friendly messages
 * @param filePath - File path to convert
 * @returns User-friendly relative path
 */
function toMessageRelativeFilePath(filePath: string): string;

import { 
  isNameTooLong, 
  shortName, 
  addTrailingPathSeparator, 
  escapePath,
  toMessageRelativeFilePath 
} from "@docusaurus/utils";

// Check name length
const longName = "very-long-filename-that-might-exceed-limits";
if (isNameTooLong(longName)) {
  const safe = shortName(longName);
  console.log(`Truncated to: ${safe}`);
}

// Add trailing separator
const dir = "/path/to/directory";
const withSeparator = addTrailingPathSeparator(dir);
// Result: "/path/to/directory/" (on Unix) or "/path/to/directory\\" (on Windows)

// Escape for code generation
const userPath = 'C:\\Program Files\\My App';
const escaped = escapePath(userPath);
// Result: "C:\\\\Program Files\\\\My App"

// User-friendly message path
const absolutePath = "/project/website/docs/guide/intro.md";
const messagePath = toMessageRelativeFilePath(absolutePath);
// Result: "docs/guide/intro.md" (relative and posix)