or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-dev.mdconfig-constants.mdcontent-management.mdcore-utilities.mddata-handling.mdfilesystem-paths.mdgit.mdindex.mdmarkdown.mdurl-web.md
tile.json

tessl/npm-docusaurus--utils

Node utility functions for Docusaurus packages providing URL handling, file operations, Git integration, i18n, Markdown processing, content visibility, and build utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@docusaurus/utils@3.8.x

To install, run

npx @tessl/cli install tessl/npm-docusaurus--utils@3.8.0

index.mddocs/

Docusaurus Utils

Docusaurus Utils provides a comprehensive collection of Node.js utility functions specifically designed for the Docusaurus ecosystem. It includes utilities for URL handling, file path operations, Git integration, internationalization (i18n), Markdown processing, content visibility management, module loading, data file operations, globbing, hashing, webpack integration, and CLI operations.

Package Information

  • Package Name: @docusaurus/utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @docusaurus/utils

Core Imports

import {
  normalizeUrl,
  posixPath,
  parseMarkdownFile,
  getFileCommitDate,
  md5Hash,
  isDraft,
  // ... other utilities
} from "@docusaurus/utils";

For CommonJS:

const {
  normalizeUrl,
  posixPath,
  parseMarkdownFile,
  getFileCommitDate,
  md5Hash,
  isDraft,
} = require("@docusaurus/utils");

Basic Usage

import {
  normalizeUrl,
  parseMarkdownFile,
  posixPath,
  md5Hash,
} from "@docusaurus/utils";

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

// Path utilities
const unixPath = posixPath("C:\\Users\\docs\\file.md");
// Result: "C:/Users/docs/file.md"

// Markdown processing
const result = await parseMarkdownFile({
  filePath: "/path/to/document.md",
  fileContent: "---\ntitle: Example\n---\n# Content",
});
// Result: { frontMatter: { title: "Example" }, content: "# Content", ... }

// Hashing utilities
const hash = md5Hash("content-to-hash");
// Result: "d85b1213473c2fd7c2045020a6b9c62b"

Architecture

Docusaurus Utils is organized into several key functional areas:

  • File System Operations: Path utilities, file globbing, and data file operations
  • URL Management: URL normalization, parsing, and path conversion utilities
  • Content Processing: Markdown parsing, content visibility, and tag management
  • Development Tools: Git integration, webpack utilities, and CLI helpers
  • Core Utilities: Hashing, regular expressions, and JavaScript helper functions
  • Configuration: Constants and default values used throughout Docusaurus

Capabilities

File System & Path Operations

Essential utilities for handling file paths, directory operations, and file system interactions with cross-platform compatibility.

function posixPath(str: string): string;
function aliasedSitePath(filePath: string, siteDir: string): string;
function isNameTooLong(str: string): boolean;
function addTrailingPathSeparator(str: string): string;

File System & Path Operations

URL and Web Utilities

Comprehensive URL handling, normalization, and web-related utilities for building and managing URLs in static site generation.

function normalizeUrl(rawUrls: string[]): string;
function fileToPath(file: string): string;
function encodePath(userPath: string): string;
function parseURLPath(urlPath: string, fromPath?: string): URLPath;

type URLPath = {
  pathname: string;
  search?: string;
  hash?: string;
};

URL and Web Utilities

Markdown Processing

Advanced Markdown processing capabilities including front matter parsing, content extraction, heading management, and link resolution.

function parseMarkdownFile(params: {
  filePath: string;
  fileContent: string;
  parseFrontMatter?: ParseFrontMatter;
  removeContentTitle?: boolean;
}): Promise<{
  frontMatter: { [key: string]: unknown };
  contentTitle: string | undefined;
  excerpt: string | undefined;
  content: string;
}>;

function parseMarkdownHeadingId(heading: string): {
  text: string;
  id: string | undefined;
};

function createExcerpt(fileString: string): string | undefined;

Markdown Processing

Content Management

Tools for managing content visibility, tags, and content organization including draft detection, tag processing, and content categorization.

function isDraft(params: { frontMatter: { [key: string]: unknown }; env?: string }): boolean;
function isUnlisted(params: { frontMatter: { [key: string]: unknown }; env?: string }): boolean;

function groupTaggedItems<Item>(
  items: readonly Item[],
  getItemTags: (item: Item) => readonly TagMetadata[]
): { [permalink: string]: TaggedItemGroup<Item> };

type TagMetadata = Tag & { inline: boolean };
type Tag = { label: string; permalink: string; description: string | undefined };

Content Management

Git Integration

Git utilities for retrieving commit information, file history, and repository metadata.

function getFileCommitDate(
  file: string,
  args: { age?: "oldest" | "newest"; includeAuthor?: boolean }
): Promise<{
  date: Date;
  timestamp: number;
  author?: string;
}>;

class GitNotFoundError extends Error {}
class FileNotTrackedError extends Error {}

Git Integration

Build & Development Tools

Development and build utilities including webpack integration, module loading, CLI helpers, and output generation.

function loadFreshModule(modulePath: string): Promise<unknown>;
function generate(
  generatedFilesDir: string,
  file: string,
  content: string,
  skipCache?: boolean
): Promise<void>;

function getFileLoaderUtils(isServer: boolean): FileLoaderUtils;
type WebpackCompilerName = "server" | "client";

Build & Development Tools

Data Handling

Utilities for data processing, file operations, globbing, and data format handling.

function readDataFile(params: {
  filePath: string;
  contentPaths: ContentPaths;
}): Promise<unknown>;

function safeGlobby(patterns: string[], options?: Globby.GlobbyOptions): Promise<string[]>;
function createMatcher(patterns: string[]): (str: string) => boolean;

type ContentPaths = {
  contentPath: string;
  contentPathLocalized: string;
};

Data Handling

Core Utilities

Foundation utilities including hashing, async operations, regular expressions, and i18n support.

function md5Hash(str: string): string;
function docuHash(strInput: string, options?: { hashExtra?: string; hashLength?: number }): string;

function mapAsyncSequential<T, R>(array: T[], action: (t: T) => Promise<R>): Promise<R[]>;
function escapeRegexp(string: string): string;

function localizePath(params: {
  pathType: "fs" | "url";
  path: string;
  i18n: I18nContext;
  options?: { localizePath?: boolean };
}): string;

Core Utilities

Configuration & Constants

Essential constants, default values, and configuration utilities used throughout the Docusaurus ecosystem.

const DEFAULT_BUILD_DIR_NAME: string;
const DEFAULT_CONFIG_FILE_NAME: string;
const DOCUSAURUS_VERSION: string;
const DEFAULT_PORT: number;
const NODE_MAJOR_VERSION: number;
const GENERATED_FILES_DIR_NAME: string;

Configuration & Constants