Developer guide

Build static HTML from the local documentation¶

This project comes with a mini documentation site to demonstrate and preview functionality. This section describes how you can build static HTML files for use in preview services like Netlify.

To build static HTML files with the latest theme changes, you must first build the theme assets, and then serve the site using the theme. The MyST site at docs/ is already configured to use this local theme build (in the .deploy folder), so to use it, run the following commands:

Install the dependencies to build the documentation

This includes both the latest version of MyST, as well as the Python dependencies to run documentation examples. Run the following command to do so:

pip install -r docs/requirements.txt

Then, build the latest version of the theme and preview the local documentation with it

make build-book
cd docs
myst build --execute --html

This will output HTML files for the documentation in docs/_build/html that you can re-use elsewhere.

You can also run this with the Make comment:

make build-docs

Previews in Pull Requests¶

We use Netlify to build the latest version of this theme from Pull Requests, and provide a preview. Ask one of the team members if you need access to its configuration.

Theme development best practices¶

Using Providers for MyST content¶

When using components that render MyST content (using <MyST ast={content} />), they must be wrapped wrap them in various providers e.g. TabStateProvider to ensure proper React context is available. These providers facilitate an alternative to prop drilling, the name used to describe passing props down through several React components. They are also used to isolate state between different subtrees, e.g. TabStateProvider defines a synchronised tab context.

See themes/book/app/routes/$.tsx#L98-L121 for examples of how the Banner and Footer components are wrapped in TabStateProvider.

Add documentation¶

We have a small demo documentation site in docs/ to provide guidance for how to use and develop the MyST react themes. As you add new features, document some basic information for others to use them.

Add a new section (or a page, if it’s a big change) with at least:

• One sentence describing of the feature.

• One sentence describing its value and when to use it.

• A few bullet points describing how to use it and expected behavior.

Documenting vs. in mystmd.org¶

Currently much of the documentation for the myst-theme is in the mystmd guide.

We are considering moving all of that documentation to the myst-theme repository so they are in one place. Follow this issue for details:

jupyter-book/myst-theme#391