API

Les cinq paquets se publient ensemble, à la même version. La plupart des projets n'ont besoin que de la commande docpensieve ; les paquets ci-dessous servent à ce qui va plus loin — un script qui génère un site, un thème à vous.

Chaque entrée vient des JSDoc des sources, que le vérificateur de types contrôle : elle ne peut pas dériver du code sans que la génération le voie. Les signatures et leurs descriptions restent en anglais, comme le code d'où elles sortent.

Pour employer l'outil plutôt que l'appeler, commencez par Installation ; les champs d'une configuration sont dans Configuration.

@docpensieve/shared

Constantes, erreurs et slugs, partagés par tous les paquets.

DOC_EXTENSIONS

DOC_EXTENSIONS

File extensions recognised as documentation pages.

CONFIG_FILENAME

CONFIG_FILENAME

Name of the configuration file init writes at the project root.

.mjs rather than .js: the file is an ES module, and Node reads a .js file as one only when the nearest package.json declares "type": "module". Elsewhere it warns on every build — or refuses the file outright when that package.json says "commonjs", as npm init -y now writes.

CONFIG_FILENAMES

CONFIG_FILENAMES

Names accepted for the configuration file, in the order they are looked for. The .js spelling still works in a project whose package.json declares "type": "module".

THEME_FOLDER

THEME_FOLDER

Folder of the project's own stylesheets, at its root. Every .css file in it is appended to the site's stylesheet, after the theme's.

DEFAULT_OUT_DIR

DEFAULT_OUT_DIR

Default output directory of a build.

VERSIONS_MANIFEST

VERSIONS_MANIFEST

Version manifest written by every build.

INDEX_SLUGS

INDEX_SLUGS

Page slugs treated as the root of their folder (they take the folder's own URL).

JSONLD_TYPES

JSONLD_TYPES

JSON-LD types supported by the jsonld.type frontmatter field.

THEME_FRAMEWORKS

THEME_FRAMEWORKS

CSS frameworks known to the ThemeEngine.

DOCUMENTATION_URL

DOCUMENTATION_URL

Public address of the documentation.

Written wherever a reader could be stuck — the foot of the help, the generated configuration, the end of init — so it lives in one place rather than in each of them.

PAGE_LAYOUTS

PAGE_LAYOUTS

Layouts accepted in a page's frontmatter.

doc is the documentation layout: menu on the left, table of contents on the right, content held to reading width. home removes all three, which is what a landing page expects.

ADMONITION_TONES

ADMONITION_TONES

Tones an admonition can take: what colours it, nothing more.

Here rather than with the component: the configuration validates the kinds a project declares, and core never imports components (ADR-002).

SNIPPET_LANGUAGES

SNIPPET_LANGUAGES

What a block of code shows of its language: a short mark, and a colour.

The colour is the one that language is known by. It is used as an accent — a rule above the block and the mark beside its name — never as a background or a text colour, so it cannot fight the theme or fail a contrast check. A project that wants none of it sets its own.

The icon name is the slug of an icon collection. It is only ever read when a project declares a set to take it from: a documentation installed in a project that has none must still build.

DocPensieveError

class DocPensieveError

Expected domain error — the CLI prints it without a stack trace.

ConfigError

class ConfigError

Configuration missing, unreadable or invalid.

LoaderError

class LoaderError

A source file could not be read or parsed.

CompileError

class CompileError

MDX/Markdown compilation failed.

StructuredDataError

class StructuredDataError

Invalid jsonld frontmatter or inconsistent structured data.

ThemeError

class ThemeError

Theme provider missing, invalid, or whose compilation failed.

GeneratorError

class GeneratorError

The site could not be generated or written.

NotImplementedError

class NotImplementedError

Milestone not implemented yet — points to the roadmap section.

slugify

slugify(input)

Turns free text into a URL-safe slug.

Accents are decomposed then dropped (Crème → creme), which keeps URLs readable instead of percent-encoded.

Renvoie string — Lowercase slug, dash-separated.

filePathToSlug

filePathToSlug(relativePath)

Converts a file path, relative to the version folder, into a page slug.

Ordering prefixes are removed from every segment: they sort the sidebar, they do not build the URL.

Renvoie string — Slug with no leading or trailing slash.

assetPathToSlug

assetPathToSlug(relativePath)

Maps an asset path into URL space.

Folders follow the page rule — ordering prefix removed, segment slugified — so that 02-guide/diagram.png lands under /guide/, where the pages of the same folder expect it. Otherwise the sorting prefix, which never shows in a page URL, would show in the URL of its images.

The file name itself stays untouched: it is the one the author writes in their Markdown, and rewriting it would break the reference.

Renvoie string — Output path, slash-separated.

blankSegments

blankSegments(relativePath)

Segments of a path that leave nothing behind once slugified.

slugify only keeps Latin letters and digits: a name made entirely of ideograms, or of punctuation, vanishes. For a page, that meant taking the home page's URL; for a folder, disappearing from the address.

Renvoie string[] — The offending segments, extension removed.

dirPathToSlug

dirPathToSlug(relativePath)

Maps a folder path into URL space.

Sibling of assetPathToSlug, but with no file name to spare: every segment goes through the page rule. Applying assetPathToSlug to a folder left its last segment untouched — 02-guide stayed 02-guide — and every relative target of a page in that folder missed the file actually copied.

Renvoie string — Output path, slash-separated.

slugToUrl

slugToUrl(slug, [versionSlug])

Converts a page slug into an absolute site URL (trailing slash included).

Renvoie string — URL starting and ending with /.

humanizeSlug

humanizeSlug(segment)

Turns a slug segment back into a readable label.

A deliberate, imperfect fallback: since slugify dropped the accents, creme-brulee comes back as “Creme brulee”. Only use it when there is no real title — the sidebar and the breadcrumb prefer the frontmatter title.

Renvoie string

orderOf

orderOf(filename)

Reads the ordering weight of a prefixed file name.

Renvoie number — The prefix number, or Infinity when absent (sorted last).

UI_STRINGS

UI_STRINGS

The shipped languages.

DEFAULT_LANGUAGE

DEFAULT_LANGUAGE

Language used when nothing else is known.

uiStrings

uiStrings([lang], [overrides])

The wording of a language, completed by English for anything it omits.

Renvoie UiStrings

pageCount

pageCount(count, strings, [lang])

Counts pages in the language of the page.

The plural category comes from the language itself, through the CLDR rules Intl carries: count === 1 is an English rule and gets French wrong on zero — "0 page", not "0 pages" — and has nothing to say about Polish or Arabic, which have four and six categories.

Renvoie string — For instance 12 pages or 1 page.

textDirection

textDirection([lang])

Writing direction of a language, for the dir attribute.

Read from the language rather than from a list of our own: Intl carries what CLDR knows, and a list would go stale the day someone translates into a language nobody thought of.

Renvoie 'ltr' \| 'rtl' — ltr when the language is unknown — the safe default, and what every page did before this existed.

isLanguageCode

isLanguageCode(value)

Whether a string names a language, as BCP 47 and CLDR understand it.

The standard is BCP 47, and Intl carries it: a regex of our own refused zh-Hans-CN, which is valid, and accepted shapes that are not. Well formed is not the same as real, though — BCP 47 allows a language subtag of five to eight letters, so francais passes that check and would land in the markup as lang="francais", a value no browser maps to a language. CLDR knows which tags name one; the subtag alone is asked, so that a region, a script or a private extension does not get in the way.

Renvoie boolean

languageName

languageName(code, [inLang])

Name of a language, written in a language.

Renvoie string — The name, or the code itself when nothing names it.

@docpensieve/core

Configuration, chargement, compilation, données structurées et génération.

DEFAULT_CONFIG

DEFAULT_CONFIG

Values applied when the user config leaves them out.

The type is spelled out: without it, TypeScript would infer versions: never[] from the empty array and refuse every read of its elements elsewhere in the file.

defineConfig

defineConfig(config)

Identity over the config, used only for autocompletion and type checking in the editor.

Renvoie T

loadConfig

loadConfig([cwd])

Loads the configuration file of a project folder.

docpensieve.config.mjs is looked for first, then docpensieve.config.js, which a project whose package.json declares "type": "module" can still use.

Renvoie Promise<DocPensieveConfig> — Normalised config.

Lève ConfigError — When no file, or two, are found, or when the file does not load or exports no object.

normalizeConfig

normalizeConfig(userConfig)

Merges the user config with the defaults and validates it.

Renvoie DocPensieveConfig — Normalised config.

Lève ConfigError — When the config is structurally invalid.

resolveVersion

resolveVersion(config, [slug])

Finds a declared version by its slug.

Renvoie Version — The requested version.

Lève ConfigError — When the slug does not exist.

DocLoader

class DocLoader

Walks a version folder and produces the list of documents.

Compiler

class Compiler

Compiles an MDX/Markdown source into an HTML fragment.

StructuredDataBuilder

class StructuredDataBuilder

Assembles a schema.org graph for a page.

SiteGenerator

class SiteGenerator

Generates the static site of one or more versions.

buildSidebar

buildSidebar(docs, [toUrl], [options])

Builds the navigation tree of a version.

The order is the DocLoader's, which has already sorted: index page first, then numeric prefixes, then alphabetical. Nothing is re-sorted here, which guarantees that the sidebar follows the reading order of the files exactly.

That order has a useful consequence: since guide/index.md is loaded before guide/installation.md, the “guide” category receives its real title before a child page creates it with a default one.

Renvoie SidebarNode[]

buildSidebarFromDescription

buildSidebarFromDescription(description, docs, [toUrl], [options])

Builds the navigation tree of a version from a description.

The description is an array of entries, kept in the order written:

• "guide/installation" — a page, by its path within the version, as in its URL; "/" is the home page. Its title becomes the label.
• { "page": "guide/installation", "label": "Install" } — the same, with a label of its own.
• { "label": "Guide", "items": [ … ], "page": "guide" } — a category, clickable when it names a page.
• { "label": "Repository", "href": "https://…" } — a link outside the site.
• { "auto": "docpensieve" } — the automatic tree of a folder: a section keeps its own menu without listing its pages one by one.

A page left out stays published: it is only absent from the menu, which is how a page is kept off it.

Renvoie SidebarNode[]

Lève ConfigError — For a path that names no page, a page listed twice, or an entry of no known kind.

collectSectionTitles

collectSectionTitles(docs)

Collects folder titles, for the breadcrumb.

Only folders with an index page have a known title; the others will be humanised from their slug by StructuredDataBuilder.

Renvoie Record<string, string> — Full folder slug to title.

foldSidebar

foldSidebar(nodes, [currentUrl])

Renvoie FoldedNode[]

MARKDOWN_COPY

MARKDOWN_COPY

File a page's Markdown copy is written to, beside its HTML.

buildFeed

buildFeed(pages, site)

Builds the RSS feed of the dated pages, newest first.

Only a page with a date enters it: a documentation page without one is reference material, not news, and dating it at build time would announce every page again at every build.

Renvoie string

buildLlms

buildLlms(pages, site)

Builds llms.txt: the index of a documentation, for a reader that is a program.

Follows the proposal as it stands: a title, a one-line summary, then a list of links, each to the Markdown copy of a page — the address of the page with index.html.md appended, since the pages are folders. A program reads that copy as the author wrote it, instead of prying the text out of the markup.

Renvoie string

buildRobots

buildRobots(sitemapUrl)

Builds robots.txt, which lets every crawler in and names the sitemap.

Renvoie string

buildSitemap

buildSitemap(pages, siteUrl)

Builds sitemap.xml.

lastmod is the page's modified date, or failing that its date; a page that carries neither is listed without one rather than with a made-up date.

Renvoie string

markdownCopy

markdownCopy(frontmatter, content, [resolve])

The Markdown copy of a page: its source, as the author wrote it.

The title is added when the page does not open on one, since a program handed the copy alone has no frontmatter to read it from. What a component draws at build time is not in the copy — a snippet's file, a grid of cards: the copy says what was written, not what was rendered.

The links are the exception. The build resolves them from the folder of the source file, and a version-root one from the version: read from where the copy is served, as written, they would lead nowhere. resolve gives each the address the HTML page carries.

Renvoie string

buildAuthorTable

buildAuthorTable(description, options)

Turns the JSON description of a version into a table of authors.

Renvoie Map<string, Author>

Lève ConfigError — When the shape is wrong, naming the offending entry.

buildByline

buildByline(frontmatter, [table], [where], [locale])

Assembles what the head of a page shows, or nothing when it has none of it.

Renvoie Byline \| null

Lève ConfigError — When a date cannot be read.

readDate

readDate(value, field, where, [locale])

Reads a date of the frontmatter, and gives it in both forms: the machine one for <time datetime>, the readable one for the reader.

A date is often written unquoted in YAML, which parses it as a Date; quoted, it arrives as text. Both are accepted, anything unreadable is refused rather than shown as Invalid Date.

Renvoie { iso: string, label: string } \| null — null when absent.

Lève ConfigError — When the value is not a date.

resolvePageAuthors

resolvePageAuthors(value, [table])

The authors of a page, in the order the frontmatter names them.

A key the table does not describe is not an error: the name is shown as written. It is what lets a project name its authors before describing them, and what keeps pages written before the file working.

Renvoie Author[]

SNIPPET_LANGUAGES

SNIPPET_LANGUAGES

Languages an extension announces, where the extension is not the name Shiki knows. Anything absent is passed on as it is written: Shiki knows far more languages than this table needs to repeat.

snippetLanguage

snippetLanguage(file)

Language of a file, from its name.

Renvoie string — A language for the highlighter, or 'text' when the name says nothing — an extensionless file is not a reason to fail.

snippetLines

snippetLines(text, [what])

The lines a snippet keeps, of the whole file.

A range is quick to write and ages badly: it means line 12 of the file as it is today. A region is a marker left in the source itself — the comment convention editors already fold on — and it follows the code when it moves, which is the whole point of naming a file rather than copying it.

Renvoie string — The lines kept, their common indentation removed.

Lève CompileError — A range that reads backwards, or a region no marker opens or closes.

snippetPath

snippetPath(source, context)

The file a snippet names, as an absolute path.

Two ways to write it, and they read differently on purpose: ./ and ../ start from the page, as a link does, while anything else starts from the root of the project — src/index.js means the same thing from every page, which is what a file of source code needs.

Renvoie string — Absolute path of the file to read.

Lève CompileError — Empty source, a relative path with no page to start from, or a file outside the project.

@docpensieve/theme

Les providers de thème et le moteur qui les compose.

BaseThemeProvider

class BaseThemeProvider

Base class to extend in order to plug in a CSS framework.

A provider generates no HTML: it supplies CSS, variables and a table of class aliases. That is what lets a single template render correctly under Tailwind as well as under the custom theme.

CustomProvider

class CustomProvider

Custom theme: hand-written CSS, no dependency.

DEFAULT_TOKENS

DEFAULT_TOKENS

Palette and measures of the light theme.

Dark mode does not live here: it fits in two blocks of custom.css, since a flat table of variables cannot express a media query.

TailwindProvider

class TailwindProvider

Tailwind theme: on-demand compilation of the classes actually used.

ThemeEngine

class ThemeEngine

Combines several providers into a single CSS output.

@docpensieve/components

Les composants disponibles dans chaque page.

classNames

classNames(parts)

Joins classes while ignoring falsy values.

A minimal equivalent of clsx: one more dependency is not worth it for six lines.

Renvoie string \| undefined — undefined when nothing is left, to avoid a class="" in the produced HTML.

cls

cls(slot, modifiers)

Class of a slot, variants included.

Renvoie string

fallbackClass

fallbackClass(slot)

Converts a slot name into a fallback class.

Renvoie string

getThemeClasses

getThemeClasses()

@returns {Record<string, string>} The current table, for inspection.

getThemeFramework

getThemeFramework()

@returns {string} The active framework, or '' when none was announced.

setThemeClasses

setThemeClasses([classes])

Declares the theme table for the whole compilation.

setThemeFramework

setThemeFramework([framework])

Declares the framework of the active theme, which ForTheme reads.

ADMONITION_KINDS

ADMONITION_KINDS

The kinds the tool ships with, each a label and a tone.

alert and danger share a tone and differ in their label and their icon: one calls for attention now, the other warns of what a wrong move costs.

Admonition

Admonition(props)

Block set apart from the text.

Lève DocPensieveError — When the kind is unknown.

getAdmonitionKinds

getAdmonitionKinds()

@returns {Record<string, { label: string, tone: string, icon?: string }>} Every kind available.

setAdmonitionKinds

setAdmonitionKinds([kinds])

Declares the kinds of the project, beside the ones shipped.

Card

Card(props)

Card container.

CardBody

Documenté dans packages/components/src/card.js.

CardFooter

Documenté dans packages/components/src/card.js.

CardHeader

Documenté dans packages/components/src/card.js.

CardImage

CardImage(props)

Image at the top of a card.

src resolves as in Markdown — relative to the page, absolute from the version root. The compiler plugins cannot handle it: they work on the Markdown tree, before React renders anything. So the component does it itself (ADR-006).

Cards

Cards(props)

Grid of cards for the children of a folder.

Lève Error — When the page list is missing, or from names nothing.

Column

Column(props)

Column of a row.

Lève DocPensieveError — Outside a Columns, or when the row mixes columns with and without a width.

Columns

Columns(props)

Row of columns.

The gap is set through className or style, with the theme's utilities: the grid recomputes the widths by itself.

Menu

Menu(props)

Menu of links.

MenuGroup

MenuGroup(props)

Group of entries, folded under a title.

In the row it opens as a panel below its title; folded, it unfolds in place rather than over the rest — on a narrow screen a panel would open off screen.

Lève DocPensieveError — Outside a Menu, or without a title.

MenuLink

MenuLink(props)

Entry of a menu.

Lève DocPensieveError — Outside a Menu, or without a target.

FallbackAfter

FallbackAfter(props)

Content shown after the period.

Without a wrapper, for the same reason as {@link FallbackBefore}.

FallbackBefore

FallbackBefore(props)

Content shown before the period.

No wrapper: a span around the author's content would become invalid markup as soon as they write a paragraph in it — which happens as soon as a blank line separates their text. The content therefore keeps its nature, inline or block.

TimeTimer

TimeTimer(props)

Shows its content during a period, with fallbacks before and after.

TOOLTIP_PLACEMENTS

TOOLTIP_PLACEMENTS

Sides the bubble can sit on.

Tooltip

Tooltip(props)

Term with a tooltip.

Lève DocPensieveError — Without text, or with an unknown side.

Tree

Tree(props)

Root of a tree.

TreeItem

TreeItem(props)

Entry of a tree.

With children, it is a collapsible branch; without, a leaf. The difference is read from the writing, with no prop to set.

Lève DocPensieveError — Outside a Tree, or without a label.

ScrollToTop

ScrollToTop(props)

Back-to-top button.

SKILL_SHAPES

SKILL_SHAPES

Shapes accepted by the gauge.

Skill

Skill(props)

Named gauge, from 0 to 100.

Lève DocPensieveError — Without a name, outside 0–100, or with an unknown shape.

Calendar

Calendar(props)

A calendar of the days its events fall on.

Every month from the first event to the last is drawn, so that an empty month between two others is not silently skipped — a gap is something a reader should see.

Lève DocPensieveError — Without an event, or with a child that is not one.

Event

Event(props)

One event of a calendar. Rendered by its calendar, never on its own.

Renvoie any — Never: it is the calendar that draws its events, and this function exists to be recognised among a calendar children — and to say so when it stands anywhere else.

Lève DocPensieveError — Always, outside a calendar.

firstWeekday

firstWeekday(year, month)

The weekday a month starts on, counted from Monday.

Zeller's congruence rather than Date: no time zone can move a day that was never a moment.

Renvoie number — 0 for Monday, 6 for Sunday.

monthGrid

monthGrid(year, month)

The weeks of a month, each of seven cells.

Renvoie (number \| null)[][] — null where the cell belongs to no day.

readDay

readDay(value)

Reads a YYYY-MM or YYYY-MM-DD.

Parsed rather than handed to new Date(): that reads a bare date as UTC and a dated-and-timed one as local, so a calendar built in one time zone showed an event a day early in another.

Renvoie { year: number, month: number, day: number } \| null

HERO_ALIGNMENTS

HERO_ALIGNMENTS

How the words sit when the banner is a single column.

HERO_SIZES

HERO_SIZES

How much room it takes. full is the height of the screen.

HERO_TONES

HERO_TONES

Tones a banner can take.

The same ones an admonition carries: a theme defines a colour per tone, not a colour per component, so a project that gives attention its own colour gives it to both at once.

Hero

Hero(props)

Head of a page: a name, a sentence, and the way in.

A HeroVisual among its children turns it into two columns — the words on one side, the picture on the other — which is what a landing page does when it has something to show. Nothing to declare: having a visual is what makes it a split.

Lève DocPensieveError — With an alignment, a size or a tone that does not exist.

HeroActions

HeroActions(props)

Row of ways in, under the sentence of a banner.

Its children are links, which Markdown writes as links: the row is what turns them into something to press, and the first one into the one meant. One primary action and one alternative is the shape that reads: a row of five is a row of none.

HeroText

HeroText(props)

The words of a banner, when it also has something to show.

Only needed in a split: on its own, a banner's children are its words already.

HeroVisual

HeroVisual(props)

The picture, the screenshot or the diagram beside the words.

Its presence is what makes a banner a split: a landing page with something to show shows it, and one without stays a single column.

Snippet

Snippet(props)

A code block, framed and labelled.

Lève DocPensieveError — With neither a file nor a block of its own.

getSnippetIcons

getSnippetIcons()

@returns {string} The collection in use, or ''.

setSnippetIcons

setSnippetIcons([prefix])

Declares the collection snippet icons are taken from.

LogoIcon

LogoIcon(props)

Project SVG icon, inlined in the page.

Lève DocPensieveError — Without src, or when the file cannot be read.

ForTheme

ForTheme(props)

Renders its children only when the site's theme is framework.

Renvoie any

Lève DocPensieveError — For a framework the configuration does not know, or when no theme was announced.

componentsCss

componentsCss()

Reads the default look of the components.

It is concatenated with the theme's by the caller: a provider that redefines a slot replaces the dp-* class with its own, and these rules then stop applying by themselves.

Renvoie Promise<string> — CSS, trimmed.

Lève DocPensieveError — When the stylesheet is missing.

getSiteContext

getSiteContext()

@returns {SiteContext} The current context.

resolveFile

resolveFile(target)

Resolves a target into a file path, for a resource read at build time.

Same landmarks as for a URL, mapped to the disk: a relative target starts from the page's file, an absolute one from the version folder. Nothing can leave that folder — a page does not read the rest of the machine.

Renvoie string — Absolute path, inside the source folder.

Lève Error — When the context is missing or the target escapes it.

resolveUrl

resolveUrl(target)

Resolves a target written by an author into a site URL.

Same rules as for Markdown content: a relative target resolves against the page's folder, an absolute target starts from the version root.

Renvoie string \| undefined — The resolved target, or as is when external.

setSiteContext

setSiteContext([page])

Declares the page being rendered.

Set by the generator before every page, like the class table.

builtinComponents

builtinComponents

Components shipped with DocPensieve.

createRegistry

createRegistry([userComponents])

Builds the component table passed to the MDX compiler.

Renvoie Record<string, Function> — Table ready for @mdx-js/mdx.

listComponentNames

listComponentNames(registry)

Lists the available component names — useful for a readable error message when an .mdx references an unknown component.

Renvoie string[] — Names sorted alphabetically.

docpensieve

Les commandes, appelables depuis un script comme depuis le terminal.

build

build(versionSlug, [options])

Renvoie Promise<void>

check

check([options])

Reads the produced site back and reports what is wrong.

Renvoie Promise<{ root: string, pages: number, faults: Fault[] }>

Lève DocPensieveError — When the folder does not exist, or when something is left to fix — the exit code is then that of an expected error, which is enough to fail a continuous integration run.

verifyLinks

verifyLinks(root, [baseUrl])

Checks the internal links of a generated site.

Exported apart from the command: it reads no configuration and addresses no one, which makes it usable elsewhere and testable on its own.

Renvoie Promise<{ pages: number, faults: Fault[] }>

verifyMarkup

verifyMarkup(root)

Checks the markup of a generated site.

Renvoie Promise<{ pages: number, faults: Fault[] }>

dev

dev([options])

Renvoie Promise<{ server: import('node:http').Server, watcher: import('chokidar').FSWatcher, port: number, url: string, close: () => Promise<void>, }>

init

init([dir], [options])

Sets up a documentation project.

Renvoie Promise<{ dir: string, theme: string, docs: boolean, translation: string, }>

Lève DocPensieveError — Unknown framework, unknown language, project already initialised, or documentation to install missing.

serve

serve([options])

Renvoie Promise<{ server: import('node:http').Server, port: number, url: string }>

Lève DocPensieveError — When the folder to serve does not exist.

createStaticServer

createStaticServer(options)

Creates a static file server.

Renvoie import('node:http').Server

listen

listen(server, port, [attempts], [host])

Starts listening, looking for a free port if needed.

On this machine only, unless asked otherwise. Called without a host, Node listens on every interface: anyone on the same network — a café, a coworking space — could read the site being written, drafts included.

Renvoie Promise<number> — The port actually used.

Lève DocPensieveError — When no port is free in the range.

resolveRequestPath

resolveRequestPath(pathname, root)

Resolves a request URL into a file path, without leaving the root.

Renvoie string \| null — Absolute path, or null when the target escapes root.