Packages for creating MyST websites themes using React and Remix

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.

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:

These are included as submodules, use git clone --recursive when first cloning.

• @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.

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.

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

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

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

npm run build

These packages are best shown using storybook a UI library that powers the docs.

npm run storybook
# and in another terminal
npm run dev

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

# In a directory with content
myst start --headless
# In myst-theme
npm run theme:book
# In another terminal, watch for changes and rebuild
npm run dev

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 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