/**
 * --------------------------------------------------------------------
 * docmd : the zero-config documentation engine.
 *
 * @package     @docmd/core (and ecosystem)
 * @website     https://docmd.io
 * @repository  https://github.com/docmd-io/docmd
 * @license     MIT
 * @copyright   Copyright (c) 2025-present docmd.io
 *
 * [docmd-source] - Please do not remove this header.
 * --------------------------------------------------------------------
 */
/**
 * Result of processing a href through the normaliser.
 */
export interface NormalizedHref {
    /** The cleaned, SEO-safe href */
    href: string;
    /** Whether the link should open in a new tab */
    isExternal: boolean;
    /** Whether the link should skip normalisation (raw file reference) */
    isRaw: boolean;
}
/**
 * Centralised internal href normaliser.
 *
 * Converts any user-written link format into a clean, SEO-optimised URL
 * that ends with a trailing slash (for directory-style pages) or is left
 * untouched (for external, hash-only, or asset links).
 *
 * Supports special prefixes:
 *   - `external:` - forces the link to open in a new tab (strips prefix)
 *   - `raw:` - bypasses normalisation (strips prefix, keeps extension)
 *
 * Supported input formats (all produce the same output):
 *   - overview.md          → overview/
 *   - overview             → overview/
 *   - overview/            → overview/
 *   - ./overview.md        → ./overview/
 *   - ../api/commands.md   → ../api/commands/
 *   - localisation/index.md  → localisation/
 *   - ./content/index.md     → ./content/
 *   - ../index.md            → ../
 *   - index.md               → (empty string - root of current dir)
 *   - /absolute/path.md      → /absolute/path/
 *   - #section               → #section (unchanged)
 *   - https://example.com    → https://example.com (unchanged, auto-external)
 *   - mailto:hi@docmd.io     → mailto:hi@docmd.io (unchanged)
 *   - external:overview.md   → overview/ (opens in new tab)
 *   - raw:docs/readme.md     → docs/readme.md (no normalisation)
 *
 * @param href  The raw href string from a markdown link, button, or nav config.
 * @returns     The normalised result with external/raw flags.
 */
export declare function resolveHref(href: string): NormalizedHref;
/**
 * Simplified normaliser for backward compatibility.
 * Returns only the normalised href string (no external/raw flags).
 * Used by navigation normalisation where external detection is handled separately.
 */
export declare function normalizeInternalHref(href: string): string;
/**
 * Recursively normalises all `path` values in a navigation tree.
 * Used for nav config from `navigation.json`, `docmd.config.js`, and the auto-router.
 *
 * Supports the `external:` prefix as a shorthand for `external: true`:
 *   { "path": "external:https://github.com" } → { "path": "https://github.com", "external": true }
 *
 * The explicit `external: true` attribute is also supported and takes precedence.
 */
export declare function normalizeNavPaths(items: any[]): void;
/**
 * Recursively normalises all `url` values in a menubar tree.
 * Applies the same trailing-slash enforcement and external detection as Markdown links.
 */
export declare function normalizeMenubarPaths(items: any[]): void;
/**
 * Sanitize a URL by collapsing consecutive slashes (except after protocol).
 * This is the last-resort safety net - if upstream logic is correct, this
 * should be a no-op.
 *
 * @example
 *   sanitizeUrl('//docs//guide/')  → '/docs/guide/'
 *   sanitizeUrl('https://a.com//b') → 'https://a.com/b'
 */
export declare function sanitizeUrl(url: string): string;