Misk-Web Docs

Contributing

Addition and updates of Misk-Web documentation is greatly appreciated! Please edit away and submit a PR with your changes keeping in mind the existing contribution guidelines for the repo.

Note: only .mdx files in this docs project is documentation that lives in docs project. If it is an .md file, it has been copied in from elsewhere and should be edited at the original location.

Architecture

Misk-Web Docs is built on Gatsby using Misk-Web components for styling and UI elements (such as the navbar).

Gatsby was chosen because of the ease of use of serving Markdown files and for the added capability of supporting MDX, which is Markdown plus the ability to include JSX components. This means that interactive documentatino with examples of components rendered inline will be possible.

External Resources

Content that exists elsewhere in the Misk-Web monorepo such as documentation within @misk/ packages or compiled demo code in the Palette tab must be manually copied in to the docs static directory in order to be served. This is done with the refresh-external.sh script.

A consequence of this is that all traditional Markdown files are considered to be copied in. Thus, any native docs files should instead use the MDX extension .mdx.

Development

Install and development exists disconnected from Rush because of existing bugs in PNPM and Rush preventing them from playing well with Gatsby. Thus, the docs site functions like a normal Javascript project island in the midst of the Rush managed monorepo.

From the docs directory, here's how you can get started:

$ npm install
$ npm run-script external
$ npm run-script build