Page Management

/**
 * Individual page or document in VuePress site
 */
class Page {
  /**
   * Create a new Page instance
   * @param options - Page configuration options
   * @param context - App instance context
   */
  constructor(options: PageOptions, context: App);
  
  /** Page metadata properties */
  readonly title: string;
  readonly path: string;
  readonly regularPath: string;
  readonly relativePath: string;
  readonly key: string;
  readonly frontmatter: any;
  readonly headers: Header[];
  readonly excerpt: string;
}

const { Page } = require("vuepress/lib/node/Page");

// Create page from file
const page = new Page({
  filePath: "/absolute/path/to/guide.md",
  relative: "guide/getting-started.md",
}, app);

// Create virtual page
const apiPage = new Page({
  path: "/api/",
  title: "API Reference",
  content: "# API Reference\n\nComplete API documentation...",
  frontmatter: {
    layout: "ApiLayout",
    sidebar: false,
  },
}, app);

// Access page properties
console.log(page.title); // "Getting Started"
console.log(page.path); // "/guide/getting-started.html"
console.log(page.relativePath); // "guide/getting-started.md"

/**
 * Process page content and metadata
 * @param options - Processing configuration
 * @returns Promise that resolves when processing is complete
 */
async process(options: ProcessOptions): Promise<void>;

interface ProcessOptions {
  /** Computed properties mixin */
  computed: any;
  /** Markdown processor instance */
  markdown: any;
  /** Page data enhancers from plugins */
  enhancers?: Enhancer[];
  /** Pre-render options */
  preRender?: any;
}

interface Enhancer {
  /** Enhancer function */
  value: (page: Page) => void | Promise<void>;
  /** Plugin name providing the enhancer */
  name: string;
}

// Process page with app's markdown processor
await page.process({
  computed: new app.ClientComputedMixinConstructor(),
  markdown: app.markdown,
  enhancers: app.pluginAPI.getOption("extendPageData").items,
});

// After processing, page data is available
console.log(`Processed: ${page.title}`);
console.log(`Headers: ${page.headers.length}`);
console.log(`Frontmatter: ${JSON.stringify(page.frontmatter, null, 2)}`);

/**
 * Serialize page metadata for client-side use
 * @returns Page data object (excludes properties starting with underscore)
 */
toJson(): PageData;

interface PageData {
  /** Page title */
  title: string;
  /** URL path */
  path: string;
  /** Unique page key */
  key: string;
  /** Page frontmatter */
  frontmatter: any;
  /** Extracted headers */
  headers?: Header[];
  /** Page excerpt HTML */
  excerpt?: string;
  /** Relative file path */
  relativePath?: string;
  /** Regular path without permalink */
  regularPath: string;
}

await page.process({ /* options */ });

const pageData = page.toJson();

// Use in site data
const siteData = {
  pages: [pageData],
  // ... other site data
};

// Client-side page data excludes internal properties
console.log(pageData.title); // "Getting Started"
console.log(pageData._content); // undefined (internal property excluded)

/**
 * Parent directory name
 */
get dirname(): string;

/**
 * File name without extension
 */
get filename(): string;

/**
 * URL-friendly slug
 */
get slug(): string;

/**
 * Stripped filename (date prefix removed if present)
 */
get strippedFilename(): string;

/**
 * Page date (from frontmatter or filename)
 */
get date(): string | null;

// Page from file: docs/2023-01-15-my-post.md
const page = new Page({
  filePath: "/path/to/docs/2023-01-15-my-post.md",
  relative: "2023-01-15-my-post.md",
}, app);

await page.process({ /* options */ });

console.log(page.dirname); // "docs"
console.log(page.filename); // "2023-01-15-my-post"
console.log(page.slug); // "my-post"
console.log(page.strippedFilename); // "my-post"
console.log(page.date); // "2023-01-15"

interface PageOptions {
  /** URL path for the page */
  path?: string;
  /** Page metadata */
  meta?: any;
  /** Page title */
  title?: string;
  /** Markdown or Vue content */
  content?: string;
  /** Absolute file path */
  filePath?: string;
  /** Relative path from source directory */
  relative?: string;
  /** Permalink URL */
  permalink?: string;
  /** Frontmatter data */
  frontmatter?: any;
  /** Permalink pattern */
  permalinkPattern?: string;
  /** Header levels to extract (default: ['h2', 'h3']) */
  extractHeaders?: string[];
}

interface Header {
  /** Header text content */
  title: string;
  /** URL anchor */
  slug: string;
  /** Header level (1-6) */
  level: number;
  /** Child headers */
  children?: Header[];
}

// Page with custom header extraction
const page = new Page({
  filePath: "/path/to/doc.md",
  extractHeaders: ["h1", "h2", "h3", "h4"], // Include h1 and h4
}, app);

await page.process({ /* options */ });

// Access extracted headers
page.headers.forEach(header => {
  console.log(`${header.level}: ${header.title} (#${header.slug})`);
  if (header.children) {
    header.children.forEach(child => {
      console.log(`  ${child.level}: ${child.title} (#${child.slug})`);
    });
  }
});

// Markdown frontmatter example
/**
 * ---
 * title: Custom Page Title
 * description: Page description for SEO
 * layout: CustomLayout
 * sidebar: false
 * prev: /previous-page/
 * next: /next-page/
 * tags:
 *   - guide
 *   - tutorial
 * ---
 */

// Vue component frontmatter example
/**
 * <frontmatter>
 * title: Vue Component Page
 * layout: ComponentLayout
 * </frontmatter>
 */

// Access frontmatter after processing
await page.process({ /* options */ });

console.log(page.frontmatter.title); // "Custom Page Title"
console.log(page.frontmatter.layout); // "CustomLayout"
console.log(page.frontmatter.sidebar); // false
console.log(page.frontmatter.tags); // ["guide", "tutorial"]

// Frontmatter affects page behavior
if (page.frontmatter.layout) {
  console.log(`Using layout: ${page.frontmatter.layout}`);
}

// Permalink pattern variables
/**
 * :year - Year from date (YYYY)
 * :month - Month from date (MM)  
 * :i_month - Month from date (M)
 * :day - Day from date (DD)
 * :i_day - Day from date (D)
 * :slug - Page slug
 * :regular - Regular path
 */

// Blog post with date-based permalink
const blogPost = new Page({
  filePath: "/path/to/2023-01-15-my-post.md",
  permalinkPattern: "/blog/:year/:month/:day/:slug.html",
}, app);

await blogPost.process({ /* options */ });

console.log(blogPost.path); // "/blog/2023/01/15/my-post.html"

// Documentation with custom permalink
const docPage = new Page({
  filePath: "/path/to/guide/advanced.md",
  frontmatter: {
    permalink: "/docs/advanced-guide/",
  },
}, app);

await docPage.process({ /* options */ });

console.log(docPage.path); // "/docs/advanced-guide/"