@std Package Overrides & Custom Blocks

This directory holds editorial override markdown files that are appended to the autogenerated Standard Library package pages.

How generation works

1. The script scripts/generate_std_docs.ts fetches overview HTML for every @std/* package from JSR.
2. It writes (or rewrites) runtime/reference/std/<package>.md with:
   • Frontmatter (title, description, version, stability)
   • An (optional) stability banner
   • The package overview (HTML fragment)
   • ## Additional Examples section containing the override markdown if a file named _overrides/<package>.md exists.
   • A preserved custom block (see below).

Adding override content

Create a file named after the package, e.g.:

_overrides/internal.md

Put any extra examples, guides, etc. in that file. On the next generation run it will appear under an "Additional Examples" heading.

Important:

• Do not include frontmatter (--- ... ---) in override files. They are appended verbatim into the generated page body; frontmatter will show up as plain text.
• Keep overrides to content sections (headings, paragraphs, code blocks, images).
• If you need to change title/description/stability, edit the generated page's frontmatter or adjust upstream JSR package metadata, not here.

Minimal example for _overrides/internal.md:

Using diff utilities

import { diffStr } from "jsr:@std/internal";
console.log(diffStr("a", "b"));

Persistent custom edits inside the generated page

If you need to add content directly inside a generated page and keep it across regenerations, use the custom block markers the generator recognizes:

<!-- custom:start -->

Your custom content here (additional sections, notes, etc.)

<!-- custom:end -->

Anything between those markers is preserved every time the generator runs. If a page has no custom block yet, a commented placeholder will be added for convenience.

Safety notes

• Do not edit outside the custom block; those areas will be replaced.
• If you rename or remove the markers, the content will be lost on the next run.
• Overrides (_overrides/<pkg>.md) are never modified by the generator; they are simply read and injected.

Regenerating

Run:

deno task generate:std-docs

This will rebuild all pages and keep both overrides and custom block content.

Skipping generation for a page (future option)

Currently every page is regenerated. If we later want a skip/manual mode, we can add a frontmatter flag (e.g. generated: false).