Content Management

/**
 * Basic tag structure with label, permalink, and optional description
 */
type Tag = {
  label: string;
  permalink: string;
  description: string | undefined;
};

/**
 * Input format for tags file (allows partial tags or null values)
 */
type TagsFileInput = Record<string, Partial<Tag> | null>;

/**
 * Normalized tags file format
 */
type TagsFile = Record<string, Tag>;

/**
 * Configuration options for tags plugins
 */
type TagsPluginOptions = {
  tags: string | false | null | undefined;
  onInlineTags: "ignore" | "log" | "warn" | "throw";
};

/**
 * Tag with metadata about whether it's inline or predefined
 */
type TagMetadata = Tag & {
  inline: boolean;
};

/**
 * Tag data for tags list pages, includes item count
 */
type TagsListItem = Tag & {
  count: number;
};

/**
 * Complete tag data for individual tag pages
 */
type TagModule = TagsListItem & {
  allTagsPath: string;
  unlisted: boolean;
};

/**
 * Front matter tag format (string or tag object)
 */
type FrontMatterTag = string | Optional<Tag, "description">;

/**
 * Determines if content is draft based on front matter and environment
 * @param params - Parameters for draft detection
 * @param params.frontMatter - Front matter object from content file
 * @param params.env - Environment override (optional)
 * @returns True if content should be treated as draft
 */
function isDraft(params: {
  frontMatter: { [key: string]: unknown };
  env?: string;
}): boolean;

/**
 * Determines if content is unlisted based on front matter and environment
 * @param params - Parameters for unlisted detection
 * @param params.frontMatter - Front matter object from content file
 * @param params.env - Environment override (optional)
 * @returns True if content should be unlisted
 */
function isUnlisted(params: {
  frontMatter: { [key: string]: unknown };
  env?: string;
}): boolean;

import { isDraft, isUnlisted } from "@docusaurus/utils";

// Check draft status
const draftFrontMatter = { title: "My Post", draft: true };
const isDraftContent = isDraft({ frontMatter: draftFrontMatter });
// Result: true

const publishedFrontMatter = { title: "Published Post" };
const isPublished = isDraft({ frontMatter: publishedFrontMatter });
// Result: false

// Check unlisted status
const unlistedFrontMatter = { title: "Hidden Post", unlisted: true };
const isHidden = isUnlisted({ frontMatter: unlistedFrontMatter });
// Result: true

// Environment overrides
const envDraft = isDraft({ 
  frontMatter: { draft: false }, 
  env: "development" 
});
// Behavior depends on environment-specific draft handling

/**
 * Normalizes front matter tag into TagMetadata
 * @param params - Tag normalization parameters
 * @param params.tag - Front matter tag to normalize
 * @param params.tagsFile - Tags file for predefined tags
 * @param params.tagsBaseRoutePath - Base route path for tag permalinks
 * @returns Normalized tag metadata
 */
function normalizeTag(params: {
  tag: FrontMatterTag;
  tagsFile: TagsFile;
  tagsBaseRoutePath: string;
}): TagMetadata;

/**
 * Normalizes array of front matter tags
 * @param params - Tags normalization parameters
 * @param params.options - Tags plugin options
 * @param params.source - Source file path for error reporting
 * @param params.frontMatterTags - Array of tags from front matter
 * @param params.tagsBaseRoutePath - Base route path for tag permalinks
 * @param params.tagsFile - Tags file for predefined tags
 * @returns Array of normalized tag metadata
 */
function normalizeTags(params: {
  options: TagsPluginOptions;
  source: string;
  frontMatterTags: FrontMatterTag[];
  tagsBaseRoutePath: string;
  tagsFile: TagsFile;
}): TagMetadata[];

/**
 * Reports usage of inline tags based on plugin options
 * @param params - Inline tags reporting parameters
 * @param params.tags - Array of tag metadata
 * @param params.source - Source file path for error reporting
 * @param params.options - Tags plugin options controlling reporting behavior
 */
function reportInlineTags(params: {
  tags: TagMetadata[];
  source: string;
  options: TagsPluginOptions;
}): void;

/**
 * Groups items by their tags, indexed by tag permalink
 * @param items - Array of items to group
 * @param getItemTags - Function to extract tags from each item
 * @returns Object mapping tag permalinks to tagged item groups
 */
function groupTaggedItems<Item>(
  items: readonly Item[],
  getItemTags: (item: Item) => readonly TagMetadata[]
): { [permalink: string]: TaggedItemGroup<Item> };

type TaggedItemGroup<Item> = {
  tag: TagMetadata;
  items: Item[];
};

/**
 * Determines tag visibility and filters items based on unlisted status
 * @param params - Tag visibility parameters
 * @param params.items - Array of items to check
 * @param params.isUnlisted - Function to determine if item is unlisted
 * @returns Visibility information and filtered items
 */
function getTagVisibility<Item>(params: {
  items: Item[];
  isUnlisted: (item: Item) => boolean;
}): {
  unlisted: boolean;
  listedItems: Item[];
};

import { 
  normalizeTag, 
  normalizeTags, 
  groupTaggedItems,
  getTagVisibility 
} from "@docusaurus/utils";

// Normalize a single tag
const tagsFile = {
  "react": {
    label: "React",
    permalink: "/tags/react",
    description: "React.js related content"
  }
};

const normalizedTag = normalizeTag({
  tag: "react",
  tagsFile,
  tagsBaseRoutePath: "/tags"
});
// Result: { label: "React", permalink: "/tags/react", description: "...", inline: false }

// Normalize tags from front matter
const frontMatterTags = ["react", "tutorial", { label: "Advanced", permalink: "/tags/advanced" }];
const normalizedTags = normalizeTags({
  options: { tags: "tags.yml", onInlineTags: "warn" },
  source: "/docs/tutorial.md",
  frontMatterTags,
  tagsBaseRoutePath: "/tags",
  tagsFile
});

// Group blog posts by tags
const blogPosts = [
  { title: "React Basics", tags: [reactTag, tutorialTag] },
  { title: "Advanced React", tags: [reactTag, advancedTag] },
];

const groupedByTags = groupTaggedItems(
  blogPosts,
  (post) => post.tags
);
// Result: { "/tags/react": { tag: reactTag, items: [post1, post2] }, ... }

// Filter unlisted content
const visibility = getTagVisibility({
  items: blogPosts,
  isUnlisted: (post) => post.unlisted === true
});
// Result: { unlisted: false, listedItems: [...] }

/**
 * Recursively flattens route configuration, returning only leaf routes
 * @param routeConfig - Array of route configuration objects
 * @returns Flattened array of leaf routes
 */
function flattenRoutes(routeConfig: RouteConfig[]): RouteConfig[];

type RouteConfig = {
  path: string;
  component?: string;
  routes?: RouteConfig[];
  // Additional route properties...
};

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

const nestedRoutes = [
  {
    path: "/docs",
    component: "DocsLayout",
    routes: [
      { path: "/docs/intro", component: "IntroPage" },
      { path: "/docs/tutorial", component: "TutorialPage" },
    ],
  },
  { path: "/blog", component: "BlogPage" },
];

const flatRoutes = flattenRoutes(nestedRoutes);
// Result: [
//   { path: "/docs/intro", component: "IntroPage" },
//   { path: "/docs/tutorial", component: "TutorialPage" },
//   { path: "/blog", component: "BlogPage" }
// ]