myst-theme

Packages for creating MyST websites themes using React and Remix.

The MyST Theme components documentation is the best way to visualize the style and structure of components.

Development

All dependencies for myst-theme are included in this repository (a monorepo!). The core themes are also included in this repository to aid in development.

What's inside?

Components:

• myst-to-react: expose MyST content as an article, built with React
• @myst-theme/frontmatter: Show title, authors and affiliations
• @myst-theme/providers: React providers for references and site configuration
• @myst-theme/demo: myst-demo component for showing syntax
• @myst-theme/diagrams: mermaid diagrams for MyST
• @myst-theme/icons: MyST icons for React
• @myst-theme/site: components and utilities for building Remix sites

Styles:

• @myst-theme/styles: Reusable style components using tailwind

Themes:

• @myst-theme/book: Designed to mimic the look-and-feel of an interactive book.
• @myst-theme/article: A single-page view of an article with associated notebooks or supporting sub-articles.

Versioning & Publishing

myst-theme uses changesets to document changes to this monorepo, call npm run changeset and follow the prompts. Later, npm run version will be called and then npm run publish.

Utilities

myst-theme is built and developed using:

• React for component rendering
• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting
• Tailwind for styling
• Storybook for documenting components

Development

First, clone the repository, then install the various dependencies:

git clone https://github.com/jupyter-book/myst-theme.git
cd myst-theme
npm install

Recommended VSCode Extensions

• Headwind: sorts the tailwind class names

Build

To build all themes and packages, run the following command:

npm run build

Develop

These packages are best shown using storybook a UI library that powers the docs. This is the same tool that powers the MyST Theme components documentation.

npm run storybook
# and in another terminal
npm run dev

Working with themes

To interact with the themes in development mode (e.g. with live-reload of components and styles as you are making changes), you need three things running at the same time (each in a different terminal window):

1. Content: A content server that serves AST to the theme server.
2. Theme: A dev server that watches for changes to this theme and re-builds it automatically.
3. Theme: The theme server / renderer application.

First, start a content server application in another MyST site (e.g., with the MySTMD guide documentation).

# Open a first terminal.
# `cd` into a directory with MyST content (e.g., the MyST docs)
# Then start a headless content server:
cd path/to/your/myst/docs
myst start --headless

The content server will parse MyST content into AST and send it to the theme server. By using --headless, we tell the content server not to start its own theme server, which allows the one we've started above to render the content.

Next, start the dev server and the theme application, which will take AST from the content server and allow you to preview changes:

# Open a second terminal in the theme repository
# First install the latest dependencies for the theme
npm install

# Start dev mode.
# This will watch for changes in the theme repository and re-build them on the fly.
# This lets you preview changes in real-time. watch for changes and rebuild
npm run dev

# Open a third terminal, and run the theme server.
# The theme server will run in a headless state.
# It will accept content from a content server, which we'll run in the next step.
npm run theme:book

Open the port that is printed in the terminal for your theme server (usually, https://localhost/3000). The theme server will start serving the AST from the content as a website at that port.

Note: in the future, this repository will likely have it's own content to test out with the themes. You can currently look to the mystjs/docs folder, or an article or a thesis.

By default, the theme server will use the same port as the content server for changes to the AST. If you'd like to use a custom port, you can do so like this:

myst start --headless --server-port 3111
CONTENT_CDN_PORT=3111 npm run theme:book

To connect to a remote content server, set the CONTENT_CDN environment variable:

CONTENT_CDN=https://remote.example.com npm run theme:book
CONTENT_CDN=https://remote.example.com npm run theme:article

Deployment

To update the theme components on NPM:

npm run version
npm run publish

To update the themes for use with the MyST CLI:

make deploy-book
make deploy-article

This updates the git repository, and sometimes is a large diff and can cause git to hang, if that happens this command can help change the buffer size when sending the diff to GitHub:

git config --global http.postBuffer 157286400