@sphido/core v3.1.0 source

@sphido/core

Sphido core package contains the two most important functions getPages() and allPages(). The getPages() function scans directories for all *.md and *.html files. The second function, allPages(), is a generator that allows you to iterate over all pages.

const pages = await getPages({path: 'content'}, /* ...extenders */);

The returned structure is very simple and looks as follows:

[
	{
		"name": "Main page",
		"path": "content/Main page.md"
	},
	{
		"name": "Directory",
		"path": "content/Directory",
		"children": [
			{
				"name": "Subpage one",
				"path": "content/Directory/Subpage one.md"
			},
			{
				"name": "Subpage two",
				"path": "content/Directory/Subpage two.md"
			}
		]
	}
]

Then iterate over the pages like this:

for (const page of allPages(pages)) {
	console.log(page);
}

Extending page object

Every single page object inside structure can be modified with extender. Extenders are set as additional parameters of the getPages() function. There are two types of extenders:

Callback extenders

Callback extender is a function that is called during recursion over each page with three parameters passed to the function page, dirent and path.

const callbackExtender = (page, dirent, path) => {
	// do anything with page object
}

const pages = await getPages({path: 'content'}, callbackExtender);

Object extenders

This extender is just a simple JavaScript object that is combined with the page object using the Object.assign() function.

const objectExtender = {
	author: 'Roman Ožana'
}

const pages = await getPages({path: 'content'}, objectExtender);

There is no limit to the number of extenders, you can combine as many as you want. Let's have the following code:

const extenders = [

	// callback extenders will be called during iteration one by one

	(page) => {
		// add property
		page.title = `${page.name} | my best website`;

		// or function
		page.getDate = () => new Date();

		// or something else
		page.counter = 1;
	},

	// callback extenders are called in the series

	(page) => {
		page.counter++;
	},

	// object extender will be merged with page object

	{
		"author": "Roman Ožana",
		"getLink": function () {
			return this.path.replace('content', 'public');
		}
	}
];

const pages = await getPages({path: 'content'}, ...extenders);

then you get this structure:

[
	{
		"name": "Main page",
		"path": "content/Main page.md",
		"title": "Main page | my best website",
		"counter": 2,
		"author": "Roman Ožana",
		"getDate": "[Function: getDate]",
		"getLink": "[Function: getLink]"
	}
]

Utility functions

The package also exports helper functions for common file operations:

  • readFile(path) — reads file content as a UTF-8 string
  • writeFile(file, content) — writes content to a file, creating parent directories if needed
  • copyFile(src, dest) — copies a file, creating destination directories if needed

Installation

Requires Node.js 22 or newer.

pnpm add @sphido/core

Example

The following example reads all *.md files in the content directory and processes them with marked into HTML files.

#!/usr/bin/env node

import { dirname, relative, join } from 'node:path';
import { getPages, allPages, readFile, writeFile } from '@sphido/core';
import slugify from '@sindresorhus/slugify';
import { marked } from 'marked';

const pages = await getPages({path: 'content'}, // ... extenders
	(page) => {
		page.slug = slugify(page.name) + '.html';
		page.dir = dirname(page.path);
	});

for (const page of allPages(pages)) {
	page.output = join('public', relative('content', page.dir), page.slug);
	page.content = marked(await readFile(page.path));

	await writeFile(page.output, `<!DOCTYPE html>
		<html lang="en" dir="ltr">
		<head>
			<meta charset="UTF-8">
			<script src="https://cdn.tailwindcss.com?plugins=typography"></script>
			<title>${page.name} | Sphido Example</title>
		</head>
		<body class="prose mx-auto my-6">${page.content}</body>
		<!-- Generated by Sphido from ${page.path} -->
		</html>
  `);
}

TypeScript

getPages() and allPages() are generic, with Page as the default — existing JavaScript and TypeScript code compiles unchanged. To get typed pages, describe what your extenders add and pass the resulting type as the generic parameter:

import { getPages, allPages, type Page } from '@sphido/core';
import { frontmatter, type WithFrontmatter } from '@sphido/frontmatter';
import { hashtags, type WithHashtags } from '@sphido/hashtags';

type BlogPage = Page & WithFrontmatter & WithHashtags & { slug: string };

const pages = await getPages<BlogPage>({path: 'content'}, frontmatter, hashtags, (page) => {
	page.slug = `${page.name}.html`; // page is typed as BlogPage
});

for (const page of allPages<BlogPage>(pages)) {
	page.title; // string | undefined — typed
	page.tags;  // typed as a Set<string>
}

The related types are exported as well:

  • Page — the base page object (name, path, optional content and children)
  • Pages<T extends Page = Page> — an array of pages, Array<T>
  • ExtenderCallback<T extends Page = Page> — (page: T, dirent: Dirent, path?: string) => Promise<void> | void
  • Extenders<T extends Page = Page> — array of callback or object extenders

Note: Page keeps an [key: string]: any index signature for backward compatibility, so types intersected with Page still allow unknown keys (they are typed any, while declared fields such as title stay precisely typed). If you want typos on unknown fields to be compile errors, define a closed page type instead of intersecting Page:

import { getPages, type Pages } from '@sphido/core';

type StrictPage = {
	name: string;
	path: string;
	content?: string;
	children?: Pages<StrictPage>;
	title?: string;
};

const pages = await getPages<StrictPage>({path: 'content'}, (page) => {
	page.title = 'ok';
	page.titel = 'typo'; // ✗ compile error
});

Source code

@sphido/core