Markdown

Functions

`importMarkdown`

function importMarkdown(dir: string, name?: string): ImportResult

TypeScript

Use importMarkdown to load an existing directory of Markdown or MDX files into a structured import result that skrypt can process and publish as documentation.

Reach for this when you already have hand-written docs, a docs/ folder, or any MDX content you want to bring into skrypt's pipeline — rather than generating docs from source code. It's the bridge between your existing content and skrypt's topic organization and site rendering.

It walks the directory recursively, treating subfolders as groups and individual .md/.mdx files as pages. Frontmatter is normalized automatically, and sort order is inferred from filename prefixes or frontmatter weight.

Name	Type	Required	Description
`dir`	`string`	Yes	Path to the Markdown/MDX directory to import. Relative paths are resolved from the current working directory.
`name`	`string`	No	Display name for the top-level group created from this directory. Defaults to the directory's folder name if omitted.

Returns an ImportResult object containing the full page tree with groups, pages, and normalized frontmatter. Pass this result to your skrypt build pipeline or merge it with generated API docs before writing output — it won't write any files on its own.

Heads up:

Directories with no .md or .mdx files return an empty result rather than throwing — check that your pages array is non-empty before proceeding.
Folder names become group slugs, so rename any folders with spaces or special characters before importing if you want clean URLs.

Example:

const path = require("path");
const fs = require("fs");

// --- Inline types (do not import from autodocs) ---
/**
 * @typedef {{ title: string, slug: string, content: string, frontmatter: Record<string, any> }} ImportedPage
 * @typedef {{ source: string, name: string, groups: any[], pages: ImportedPage[] }} ImportResult
 */

// --- Minimal mock of importMarkdown behavior ---
function findMdxFiles(dir) {
  if (!fs.existsSync(dir)) return [];
  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
    const fullPath = path.join(dir, entry.name);
    if (entry.isDirectory()) return findMdxFiles(fullPath);
    if ([".md", ".mdx"].includes(path.extname(entry.name))) return [fullPath];
    return [];
  });
}

function importMarkdown(dir, name) {
  const resolvedDir = path.resolve(dir);
  const folderName = name || path.basename(resolvedDir);
  const files = findMdxFiles(resolvedDir);

  const pages = files.map((filePath) => {
    const raw = fs.readFileSync(filePath, "utf-8");
    const slug = path
      .relative(resolvedDir, filePath)
      .replace(/\\/g, "/")
      .replace(/\.mdx?$/, "");

    // Extract title from first H1 or filename
    const titleMatch = raw.match(/^#\s+(.+)/m);
    const title = titleMatch ? titleMatch[1] : path.basename(filePath, path.extname(filePath));

    return { title, slug, content: raw, frontmatter: {} };
  });

  return {
    source: "markdown",
    name: folderName,
    groups: [],
    pages,
  };
}

// --- Demo: import an existing docs directory ---
const DOCS_DIR = "./docs/guides";

// Create sample files so the example is fully self-contained
fs.mkdirSync(path.join(DOCS_DIR, "authentication"), { recursive: true });
fs.writeFileSync(path.join(DOCS_DIR, "quickstart.md"), "# Quickstart\nGet up and running in 5 minutes.");
fs.writeFileSync(path.join(DOCS_DIR, "authentication/oauth.mdx"), "# OAuth 2.0\nConfigure OAuth for your app.");

try {
  const result = importMarkdown(DOCS_DIR, "Guides");

  console.log("Import result:");
  console.log(`  name:  ${result.name}`);
  console.log(`  pages: ${result.pages.length}`);
  result.pages.forEach((p) => {
    console.log(`    - [${p.title}]  slug: ${p.slug}`);
  });

  // Expected output:
  // Import result:
  //   name:  Guides
  //   pages: 2
  //     - [Quickstart]  slug: quickstart
  //     - [OAuth 2.0]   slug: authentication/oauth
} catch (err) {
  console.error("Import failed:", err.message);
} finally {
  fs.rmSync("./docs", { recursive: true, force: true });
}

TypeScript

import — markdown

Markdown

Functions

importMarkdown

`importMarkdown`