feat(doc): add specification#723
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #723 +/- ##
=======================================
Coverage 76.15% 76.15%
=======================================
Files 151 151
Lines 13641 13641
Branches 1066 1066
=======================================
Hits 10388 10388
Misses 3248 3248
Partials 5 5 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Adds a formal Markdown specification for the documentation format parsed by @node-core/doc-kit, intended to codify the supported structure and metadata conventions (and to address #402’s request to define a ruleset).
Changes:
- Introduces
docs/specification.mddescribing document structure, heading semantics, YAML-in-HTML-comment metadata, stability indicators, typed parameter lists, and cross-references. - Defines (in spec) a
<!--module=...-->directive for scoping sub-sections to a module.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ovflowd
left a comment
ovflowd
left a comment
There was a problem hiding this comment.
SGTM! Really good stuff, this is phenomenal work. I've left a few comments!
avivkeller
force-pushed
the
specification
branch
from
6b39ab9 to
da789c7
Compare
|
| File | Base | Head | Diff |
|---|---|---|---|
orama-db.json |
8.08 MB | 8.08 MB | +1.00 B (+0.00%) |
|
cc @nodejs/web-infra would be good to have more reviews before we land this! |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
This is a great start! Excellent work.
github-merge-queue
Bot
removed this pull request from the merge queue due to no response for status checks
|
I'm late to this - but this is really stellar! |
Closes #402
This PR introduces a formal specification for the Markdown format consumed by doc-kit. I drafted it over the past few days while thinking through how to align webpack's documentation output (for our GSoC) with doc-kit's parseable structure, then revised and formalized it with AI.
The specification documents the Markdown we currently support. However, it defines a
<!--module=node:fs/promises-->directive, as @Ethan-Arrowood proposed in #402. This allows sub-sections of a document to be associated with a specific module when needed (see §4.4.4 and §6.2.6).