markdown-magic

@fluid-tools/markdown-magic

This library contains tools for generating and embedding documentation contents in Markdown documentation.

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.

Usage

Script

To run the markdown-magic script against your Markdown files, run the following from the command line:

npm run markdown-magic [--files <one or more file globs, space-separated>] [--workingDirectory <directory in which to run the script>]

Arguments

files

Accepts one or more glob values to match against. Only file names matching the pattern(s) will have their contents parsed and updated.

Uses the globby format.

Default: **/*.md

Example

npm run markdown-magic --files \"docs/*\" \"!docs/README.md\"

Will run on all Markdown contents under the docs directory, except for !docs/README.md.

workingDirectory

Specifies the directory from which the script will be run. Useful when the directory from which the Node.js process is run is not the hierarchical root from which you wish to run documentation generation.

Default: Node.js's working directory (i.e. the directory from which the script was executed).

Example

npm run markdown-magic --workingDirectory ../../

Will run the script from two levels higher in the file structure relative to where the npm script itself was executed.

Transforms

The following is a list of supported transform pragmas that can be included in your Markdown documentation to automatically generate / embed contents.

To include a transform in your document, use the following syntax:

<!-- AUTO-GENERATED-CONTENT:START (<transform-name>[:<argument-1>=<value-1>[&<argument-2>=<value-2>...&<argument-N>=<value-N>]]) -->
<!-- AUTO-GENERATED-CONTENT:END -->

INCLUDE

Can be used to embed contents from another file into the Markdown file.

Arguments:

• path: Relative path from the document to the file being embedded.
• start: (optional) First line from the target file to be embedded (inclusive). If positive, the value is relative to the beginning of the file. If negative, the value is relative to the end of the file.
• end: (optional) Limit line from the target file to be embedded (exclusive). If positive, the value is relative to the beginning of the file. If negative, the value is relative to the end of the file.

LIBRARY_README_HEADER

Generates simple "header" contents for a library package README. Contains instructions for installing the package and importing its contents.

Generally recommended for inclusion after a brief package introduction, but before more detailed sections.

Notes:

• This strictly intended as a starter template to remove the need for some handwritten boilerplate. You will still need to fill in semantic and usage information.
• This is effectively just a wrapper around lower-level templates. If you want more fine-grained control over the content structure, we recommend using other templates.
  • PACKAGE_SCOPE_NOTICE
  • INSTALLATION_INSTRUCTIONS
  • IMPORT_INSTRUCTIONS
  • API_DOCS

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• packageScopeNotice: (optional) Override the automatic scope detection behavior with an explicit scope kind: FRAMEWORK, EXPERIMENTAL, INTERNAL, PRIVATE, TOOLS, or EXAMPLE.
• installation: Whether or not to include the package "Installation" section.
  • Default: true.
  • See INSTALLATION_INSTRUCTIONS.
• devDependency: Whether or not the package is intended to be installed as a dev dependency.
  • Default: false.
  • Only observed if installation is true.
• apiDocs: Whether or not to include a section pointing to the library's generated API documentation on fluidframework.com.
  • Default: true if the package is intended for direct public use. false otherwise.
  • Assumes that the package is published, uses API-Extractor, and has its documentation published under fluidframework.com/apis/<package-name>.
  • See API_DOCS

EXAMPLE_APP_README_HEADER

Generates a complete starter README.md file for a Fluid example app package.

Notes:

• This strictly intended as a starter template to remove the need for some handwritten boilerplate. You will still need to fill in semantic and usage information.
• This is effectively just a wrapper around lower-level templates. If you want more fine-grained control over the content structure, we recommend using other templates.
  • EXAMPLE_GETTING_STARTED

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• gettingStarted: Whether or not to include a simple "getting started" usage section.
  • Default: true.
  • See EXAMPLE_GETTING_STARTED.
• usesTinylicious: Whether or not running the example app requires running Tinylicious from another terminal.
  • Default: true.
  • Only observed if gettingStarted is true.

README_FOOTER

Generates simple "footer" contents for a package README.

Generally recommended for inclusion at the end of the README.

Notes:

• This is strictly intended as a starter template to remove the need for some handwritten boilerplate. You will still need to fill in semantic and usage information.
• This is effectively just a wrapper around lower-level templates. If you want more fine-grained control over the content structure, we recommend using other templates.
  • PACKAGE_SCRIPTS
  • CLIENT_REQUIREMENTS
  • CONTRIBUTION_GUIDELINES
  • HELP
  • TRADEMARK

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• scripts: Whether or not to include a section listing the package's npm scripts.
  • Default: false.
  • See PACKAGE_SCRIPTS.
• clientRequirements: Whether or not to include a section outlining the minimum client requirements for using Fluid Framework packages.
  • Default: true if the package is intended for direct public use. false otherwise.
  • See CLIENT_REQUIREMENTS.
• contributionGuidelines: Whether or not to include a section enumerating fluid-framework's contribution guidelines.
  • Default: true.
  • See CONTRIBUTION_GUIDELINES.
• help: Whether or not to include a simple "help" section, which points the reader to various resources.
  • Default: true.
  • See HELP.
• trademark: Whether or not to include a section containing our Microsoft trademark.
  • Default: true.
  • See TRADEMARK.

EXAMPLE_GETTING_STARTED

Generates a simple "getting started" usage section for a Fluid example app README.

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• usesTinylicious: Whether or not running the example app requires running Tinylicious from another terminal.
  • Default: true.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

API_DOCS

Generates a README section pointing to the library's generated API documentation on fluidframework.com.

Assumes that the package is published, uses API-Extractor, and has its documentation published under fluidframework.com/apis/<package-name>.

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

INSTALLATION_INSTRUCTIONS

Generates a README section including package installation instructions.

Assumes that the package is published and can be installed via npm.

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

DEPENDENCY_GUIDELINES

Generates a README section with fluid-framework dependency guidelines.

Assumes that the package is published and can be installed via npm.

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

IMPORT_INSTRUCTIONS

Generates a README section including instructions for how to import from Fluid Framework library packages. Accounts for our use of package.json exports. Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

EXAMPLE_GETTING_STARTED

Generates a "Getting Started" section for an example app README. Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• usesTinylicious: Whether or not running the example app requires running Tinylicious from another terminal.
  • Default: true.

CLIENT_REQUIREMENTS

Generates a section containing minimum client requirements for using Fluid Framework packages.

See the corresponding template here.

Arguments:

• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

TRADEMARK

Generates a section containing our Microsoft trademark.

See the corresponding template here.

Arguments:

• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

CONTRIBUTION_GUIDELINES

Generates a section enumerating fluid-framework's contribution guidelines.

See the corresponding template here.

Arguments:

• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

HELP

Generates a simple "help" section, which points the reader to various resources.

See the corresponding template here.

Arguments:

• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

PACKAGE_SCRIPTS

Generates a section containing a table enumerating the package's npm scripts.

Arguments:

• packageJsonPath: Relative file path to the library package's package.json file. Used for generation of package metadata.
  • Default: ./package.json.
• includeHeading: Whether or not to include a section heading above the generated contents.
  • Default: true.
• headingLevel: Root heading level for the generated section. Must be a positive integer.
  • Default: 2.

PACKAGE_SCOPE_NOTICE

Generates a user-facing notice about target audience and support characteristics of the package based on its scope. By default, it generates the appropriate notice based on the package name's scope (if it's one the system recognizes), but this can be overridden by specifying scopeKind.

Arguments:

• packageJsonPath: : Relative file path to the library package's package.json file. Used to read the package name's scope (when the scopeKind argument is not provided).
  • Default: ./package.json.
• scopeKind: (optional) Override the automatic scope detection behavior with an explicit scope kind: FRAMEWORK, EXPERIMENTAL, INTERNAL, PRIVATE, TOOLS, or EXAMPLE.

Contribution Guidelines

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 [email protected] 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.

Help

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!

Trademark

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.