# @markuplint/spec-generator

> Generates @markuplint/html-spec

Latest version **4.18.0** (published 2026-04-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install @markuplint/spec-generator
pnpm add @markuplint/spec-generator
yarn add @markuplint/spec-generator
bun add @markuplint/spec-generator
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 4.18.0 |
| Published | 2026-04-22 |
| First published | 2023-11-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 7 |
| Unpacked size | 158.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 627 |
| Author | Yusuke Hirao |
| Maintainers | yusukehirao |

## Links

- npm: https://www.npmjs.com/package/@markuplint/spec-generator
- Repository: https://github.com/markuplint/markuplint
- Homepage: https://github.com/markuplint/markuplint#readme
- Issues: https://github.com/markuplint/markuplint/issues
- npm.io page: https://npm.io/package/@markuplint/spec-generator

## Dependencies (7)

- [ajv](https://npm.io/package/ajv.md) 8.18.0
- [glob](https://npm.io/package/glob.md) 13.0.6
- [cheerio](https://npm.io/package/cheerio.md) 1.2.0
- [cli-progress](https://npm.io/package/cli-progress.md) 3.12.0
- [@types/cheerio](https://npm.io/package/@types/cheerio.md) 1.0.0
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) 5.7.1
- [strip-json-comments](https://npm.io/package/strip-json-comments.md) 5.0.3

## Recent versions

- 4.18.0 (latest) — 2026-04-22
- 4.18.4 (v4) — 2026-10-22
- 5.0.0-rc.1 (next) — 2026-03-27
- 5.0.0-dev.5 (canary) — 2026-02-27
- 5.0.0-rc.0 — 2026-03-12
- 5.0.0-alpha.3 — 2026-02-26
- 5.0.0-alpha.2 — 2026-02-23
- 5.0.0-alpha.1 — 2026-02-22
- 5.0.0-alpha.0 — 2026-02-20
- 4.8.2 — 2026-02-10
- 4.8.1 — 2025-11-05
- 4.8.0 — 2025-08-24
- 4.7.0 — 2025-08-13
- 4.6.19 — 2025-04-13
- 4.6.19-dev.110 — 2025-04-13
- … 46 more at https://npm.io/package/@markuplint/spec-generator/versions

## README

# @markuplint/spec-generator

Private builder used to generate `@markuplint/html-spec`.

It assembles an Extended Spec JSON from the HTML element source files and external references
(MDN, WAI-ARIA, HTML-ARIA), then writes `index.json` in `@markuplint/html-spec`.

## How it is invoked

Called from `packages/@markuplint/html-spec/build.mjs`:

```ts
await main({
  outputFilePath: 'index.json',
  htmlFilePattern: 'src/spec.*.json',
  commonAttrsFilePath: 'src/spec-common.attributes.json',
  commonContentsFilePath: 'src/spec-common.contents.json',
});
```

You normally don't run this directly; use:

- From repo root: `yarn up:gen`
- Only html-spec: `yarn workspace @markuplint/html-spec run gen`

## What it does

1. **Read element sources** -- Load every `src/spec.*.json` and infer the element name from the filename
2. **Enrich from MDN** -- Fetch MDN element pages for descriptions, categories, and attribute metadata (manual specs take precedence)
3. **Add obsolete elements** -- Inject HTML obsolete elements and deprecated SVG elements
4. **Load shared data** -- Read global attributes and content model definitions
5. **Build ARIA definitions** -- Scrape WAI-ARIA (1.1/1.2/1.3), Graphics-ARIA, and HTML-ARIA
6. **Emit Extended Spec JSON** -- Write `{ cites, def, specs }` to `index.json`

For detailed architecture and data flow, see [ARCHITECTURE.md](ARCHITECTURE.md).

## Precedence rules

- Manual data in `src/spec.*.json` overrides MDN-scraped values on conflict.
- Attribute objects are merged per name; manual keys win, MDN may fill missing flags.
- Shared files under `src/spec-common.*.json` are imported as-is.

## Network and caching

- Uses live HTTP fetch against MDN/W3C specs. There is an in-process cache for the current run only.
- If a fetch fails, the entry may be left empty; re-run later or edit your manual source to cover it.

## When to change this package

- Only when the scraping targets change (DOM structure/URLs), or when the Extended Spec shape evolves
  in `@markuplint/ml-spec`.

## Documentation

- [ARCHITECTURE.md](ARCHITECTURE.md) -- Package overview, module structure, data flow
- [docs/modules.md](docs/modules.md) -- Detailed reference for each source module
- [docs/scraping.md](docs/scraping.md) -- Web scraping targets, CSS selectors, and error handling
- [docs/maintenance.md](docs/maintenance.md) -- Troubleshooting, common recipes, and debugging

Japanese versions are also available:

- [ARCHITECTURE.ja.md](ARCHITECTURE.ja.md)
- [docs/modules.ja.md](docs/modules.ja.md)
- [docs/scraping.ja.md](docs/scraping.ja.md)
- [docs/maintenance.ja.md](docs/maintenance.ja.md)

## See also

- `@markuplint/html-spec` README -- how to edit the element sources.
- `@markuplint/ml-spec` README -- schema shapes, generation, and spec merging.

---
_Source: https://npm.io/package/@markuplint/spec-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._