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

This repository depends on themes which are brought in as a sub-module. When first cloning the repository use git clone --recursive, then install the various dependencies:

git clone --recursive https://github.com/executablebooks/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:

1. a content server
2. the renderer/application (theme)
3. a process watching all components

First, start the theme application:

# Install dependencies
npm install
# First, build the theme
npm run build

# Then start the theme
npm run theme:book
# In another terminal, watch for changes and rebuild
npm run dev

Then, start the content server application in e.g. the mystmd docs:

# In a directory with content
myst start --headless

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.

To run on a specific port (for example, developing locally between two projects), you can specify a custom port with:

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