THE GITHTML FIELD GUIDE
Control TypeDoc scope before sharing an API reference
Define TypeDoc’s entry points and inclusion rules before treating its output as the public API reference. Review the generated symbol list against the package’s supported interface. Scope settings are documentation controls, not a security boundary: private implementation details and sensitive comments still need appropriate source handling and a review of the actual distributed files.
Write the audience contract
Decide whether the reference serves package consumers, internal maintainers, or contributors. Consumers usually need supported exports and practical usage notes; maintainers may need internal relationships. A single indiscriminate reference can overwhelm the first audience and still underserve the second.
List a few symbols that must appear and a few that should not. These examples become an acceptance checklist for the configuration rather than relying on a vague impression that the generated sidebar looks reasonable.
Choose entry-point behavior deliberately
TypeDoc supports different entry-point strategies, including resolving specified entry points and expanding directories. The example configuration deliberately names one entry point with the resolve strategy. Adapt it to the existing project instead of replacing established settings blindly.
Review exclusion and visibility options in the documentation for the installed TypeDoc version. Different projects have different needs, and hiding a symbol in one presentation is not equivalent to removing sensitive content from every generated artifact or source link.
{
"entryPoints": ["src/index.ts"],
"entryPointStrategy": "resolve",
"out": "build/api-reading"
}Inspect relationships, not only names
Check whether public types reference omitted internal types in ways that leave the reader stranded. A clean top-level list can still contain confusing links or unresolved descriptions. Review representative nested types and examples before approving the scope.
Also inspect source links, comments, and supplementary documents. These can reveal internal paths or context even when the main symbol list appears appropriately limited. Handle confidentiality at the content and distribution layers, not by assuming a theme hides everything unwanted.
Maintain scope across releases
Compare the generated public surface when releases add or remove exports. Ask whether a change is intentional, a configuration effect, or a documentation regression. Record the source revision and the reviewed entry-point settings with the build.
For gitHtml reading copies, prefer a focused reference subset only when it remains understandable independently. Include a link to the complete authorized reference and explain the subset’s limits. Readers should know whether a symbol is absent because it is unsupported or simply outside this packet.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.