Contains a programmatic API for generating Markdown documentation from an API report generated by API-Extractor.
Note: this library is specifically configured to target GitHub flavored Markdown.
Compatibility with other Markdown flavors is not guaranteed, though you can always write your own renderer implementation against our Documentation Domain!
It is similar to API-Documenter and is heavily based upon it and uses it under the hood, but is designed to be more extensible and can be used programmatically.
Note: this library does not currently offer a Command Line Interface (CLI). One may be added in the future, but for now this library is intended to be consumed programmatically.
The following terms are leveraged heavily in this package's APIs and documentation.
- API Model: Refers to a complete API suite, comprised of one or more packages.
This often corresponds to all of the packages in the mono-repo, or a series of packages whose API docs are published together.
It is generally represented via the ApiModel type, from the @microsoft/api-extractor-model library.
- In some places, this library refers to an
API Model
in terms of a directory or directory path. In these cases, it is referring to a directory that contains the set of.api.json
files (generated per-package byAPI-Extractor
).
- In some places, this library refers to an
- API Item: Refers to a single TypeScript item exported by one or more packages in the
API Model
. It is generally represented via the ApiItem type, from the @microsoft/api-extractor-model library. E.g., an exported interfaceFoo
would be captured by API Extractor as a single API item (an ApiInterface). Alternatively, an exported enumFoo
with flagsBar
andBaz
would be captured as 1 API item (an ApiEnum) forFoo
, with 2 child API items for the flagsBar
andBaz
(ApiEnumMembers).- This is the granularity by which documentation is generated, and the granularity at which most configuration options are presented.
NOTE: This package is a library intended for use within the microsoft/FluidFramework repository. It is not intended for public use. We make no stability guarantees regarding this library and its APIs.
To get started, install the package by running the following command:
npm i @fluid-tools/api-markdown-documenter -D
This package leverages package.json exports to separate its APIs by support level. For more information on the related support guarantees, see API Support Levels.
To access the public
(SemVer) APIs, import via @fluid-tools/api-markdown-documenter
like normal.
To access the beta
APIs, import via @fluid-tools/api-markdown-documenter/beta
.
This library is intended to be highly customizable. That said, it is also intended to be easy to use out of the box.
Are you using API-Extractor?
Are you already generating .api.json
report files as a part of your build?
If yes, create a file called api-markdown-documenter.js
and paste the following code:
const { loadModel, MarkdownRenderer } = require("@fluid-tools/api-markdown-documenter");
const inputDir = "<PATH-TO-YOUR-DIRECTORY-CONTAINING-API-REPORTS>";
const outputDir = "<YOUR-OUTPUT-DIRECTORY-PATH>";
// Create the API Model from our API reports
const apiModel = await loadModel(inputDir);
const config = {
apiModel,
uriRoot: ".",
};
await MarkdownRenderer.renderApiModel(config, outputDir);
The above script can be invoked as an npm
script by adding the following to your package.json
's scripts
property:
"generate-api-docs": "node ./api-markdown-documenter.js"
The above steps omit many of the configuration options exposed by the library. For more advanced usage options, see the following sections.
This package contains 2 primary, programmatic entry-points for generating documentation:
The transformApiModel
function accepts an ApiModel representing the package(s) of a repository, and generates a sequence of "Document" Abstract Syntax Tree objects representing the resulting documentation based on the other provided configuration options.
These objects include information about the page item, its documentation contents, and the intended output file path the document file should be rendered to, based on provided options.
- These trees are backed by unist's AST model.
The input ApiModel
here will generally be the output of API-Extractor.
See Documentation Domain below for more details on the output format.
Note: TSDoc
's parser has limited support for preserving HTML
tags in TSDoc
comments.
This library does not preserve embedded HTML
in doc comments.
Instead, any HTML
tags found will be discarded, and the contents within will be rendered normally.
This matches VSCode Intellisense's behavior.
We may reconsider this in the future.
The MarkdownRenderer
namespace includes a few functions for generating Markdown contents.
The MarkdownRenderer.renderApiModel
function operates like transformApiModel, but writes the resulting documents to disk as files based on the provided configuration options.
This function accepts overrides for all of its default Markdown
-rendering behaviors, so feel free to customize as you see fit!
Both of the rendering APIs above take as input an ApiModel
object that describes the API suite being processed.
To generate an API model from .api.json
files generated by API-Extractor
, see the loadModel
function, which can generate an ApiModel
for you, given a path to a directory containing the API reports.
If you are using the transformApiModel option described above, one option for emitting Markdown string content is to use the emitMarkdown
function.
It accepts a MarkdownDocument
object as input, and outputs a string representing the final Markdown content.
Note: you can also accomplish this by just using MarkdownRenderer.renderApiModel if you are using default configuration / emitter options.
As mentioned above, this library was designed in an attempt to be highly flexible and configurable. Each layer in the system has its own configuration with a suite of options that you can customize to meet your needs.
Some of the configs may contain a large number of options, but fret not! The vast majority of these options have default values that have been crafted to produce high quality documentation for your library with minimal specification.
As noted above, this library is intended to be consumed programmatically. While we may at some point add some command line interfaces for common paths, the primary goal of this library's architecture is to be flexible and extensible. To that end, we have broken its logic into a few isolable steps, each offering its own extensibility offerings.
End to end, this library can be viewed as a pseudo-functional transformation pipeline mapping from an APIModel generated by API-Extractor
to one or more Markdown
or HTML
formatted document files.
But this is broken into the following internal sequences:
---
title: Markdown
---
graph LR
A[ApiModel]
B[Documentation AST]
C[Markdown AST~]
D[raw Markdown]
A-->|transformApiModel|B
B-->|documentToMarkdown~|C
C-->|MarkdownRenderer.renderMarkdown~|D
A-.->|MarkdownRenderer.renderApiModel|D
B-.->|MarkdownRenderer.renderDocument|D
---
title: HTML
---
graph LR
A[ApiModel]
B[Documentation AST]
C[HTML AST]
D[raw HTML]
A-->|transformApiModel|B
B-->|documentToHtml|C
C-->|HtmlRenderer.renderHtml|D
A-.->|HtmlRenderer.renderApiModel|D
B-.->|HtmlRenderer.renderDocument|D
Note: APIs above marked with an *
are in preview, and may change without notice.
Note: APIs above marked with an ~
are planned, but do not yet exist.
For more details on the interior Documentation AST
(Abstract Syntax Tree) domain, see Documentation Domain below.
The input to our system is the ApiModel generated by API-Extractor.
This library offers the loadModel
function as an option for loading your model from the generated .api.json
metadata files API-Extractor
generates be default.
To transform this input to our [Documentation Domain][], you may call the transformApiModel
function.
This function walks the input ApiModel
tree, transforming each ApiItem
under it according to its configured series of transformation policies.
These policies are entirely configurable, though the system offers defaults out of the box.
This library defines its own "Documentation Domain" using Abstract Syntax Tree (AST) syntax backed by unist.
This is used as an intermediate domain between the API-Extractor
-based input, and the Markdown
rendering output.
This domain was crafted to support TSDoc's capabilities, and to represent something resembling lowest common denominator between Markdown
and HTML
syntax.
As this domain is implemented as an AST
, it is highly customizable.
If you are interested in creating your own intermediate domain concepts, feel free to implement them.
So long as you provide a corresponding rendering handler, the system will gladly accept them!
The final component of this library's transformation pipeline is its Markdown
renderer.
Note: by default, this renderer is configured to generate GitHub flavored Markdown.
Compatibility with other Markdown flavors is not guaranteed by default.
As with the other logic in this library, the renderer is highly configurable.
It will accept any Documentation Domain
tree as input, and transform each node according to its configured render policies.
If you would like to add rendering support for a custom Documentation Domain
node type, simply provide a rendering handler associated with that node's type
value.
If you would like to change any or all of this library's default rendering policies, you may simply override the default policies for the desired type
s.
This library now includes APIs for HTML rendering.
Like the MarkdownRenderer, we offer a HtmlRenderer.renderApiModel
function that operates in much the same way, but outputs HTML
-formatted documents instead of Markdown.
The following APIs are still in preview, and may change without notice. Use at your own risk.
This library now includes APIs for transforming Documentation Domain
trees to HTML syntax trees using hast.
This library includes a preview API for "linting" an API Model.
To use, import the lintApiModel
function from @fluid-tools/api-markdown-documenter/beta
.
This function returns a set of TSDoc-related "errors" discovered while walking the API Model.
The primary goal of this tool is to detect issues that API-Extractor
cannot validate on a per-package basis when generating API reports.
For now, this is limited to validating @link
and @inheritDoc
tags to ensure that symbolic references are valid within the API Model.
Other validation may be added in the future as needed.
- Add extensibility options for
DocNode
transformations- If a consumer has a custom tsdoc config associated with their API-Extractor setup, this will be needed.
- Intro sandbox (api report)
- Extensibility examples (maybe use the "AlertNode" concept used by the fluidframework.com build)
- Fix links to the same file (only need heading component, not file path)
- This will require plumbing down a context document item, so we can easily determine if the document to which the link is being generated is the same as the document being linked to.
- Update exported utilities to accept partial configs, rather than needing the user to provide a complete configuration.
- Config options for parsing TSDoc block comment contents as Markdown (and don't escape the contents)?
- Add support for Table Cell alignment
- Rather than repeatedly walking up a given
ApiItem
's hierarchy when evaluating paths, links, etc., we could pass down transformation context object containing a running record of the item's hierarchy as we walk the tree.
- Support placing documents within their own hierarchy (support for the "index" model used by systems like DocFX)
- Pre-canned policies (flat, index, adjacency)
- Add
documentToMarkdown
API that generatesmdast
output.- Update Markdown rendering APIs to leverage the
mdast
andhast
domain outputs.
- Update Markdown rendering APIs to leverage the
There are many ways to contribute to Fluid.
- Participate in Q&A in our GitHub Discussions.
- Submit bugs and help us verify fixes as they are checked in.
- Review the source code changes.
- Contribute bug fixes.
Detailed instructions for working in the repo can be found in the Wiki.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Not finding what you're looking for in this README? Check out fluidframework.com.
Still not finding what you're looking for? Please file an issue.
Thank you!
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.