diff --git a/.changeset/spotty-planets-fetch.md b/.changeset/spotty-planets-fetch.md new file mode 100644 index 0000000000..26674b92a9 --- /dev/null +++ b/.changeset/spotty-planets-fetch.md @@ -0,0 +1,5 @@ +--- +"myst-transforms": patch +--- + +Add support for `class` in block data diff --git a/docs/deployment.md b/docs/deployment.md index 45ca702b07..7b3978b3c8 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -23,7 +23,7 @@ The high-level differences between these approaches are outlined in [](#deployme :::{note} MyST was designed to be deployed as an application Deploying MyST as an application has many benefits. For example, [performance enhancements](./accessibility-and-performance.md) (like pre-fetching for instant page-transitions, loading indicators, and smaller network payloads) and easier upgrades as new MyST versions are released. -The [default themes](website-templates.md#themes-bundled-with-myst) for MyST are designed to be MyST applications rather than static sites, but the core functionality is equally shared between the two options. +The [default themes](#default-web-themes) for MyST are designed to be MyST applications rather than static sites, but the core functionality is equally shared between the two options. ::: % - Static deployments are MPA (each page own HTML document), SSG (rendered ahead of time) diff --git a/docs/myst.yml b/docs/myst.yml index cf10ac3d71..1f41b43614 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -167,3 +167,5 @@ site: title: MyST Markdown Guide domains: - mystmd-guide.curve.space + options: + style: public/style.css diff --git a/docs/public/style.css b/docs/public/style.css new file mode 100644 index 0000000000..7766fa1f84 --- /dev/null +++ b/docs/public/style.css @@ -0,0 +1,5 @@ +.text-gradient em { + background: -webkit-linear-gradient(#eee, #333); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; +} diff --git a/docs/website-style.md b/docs/website-style.md index defb7ddaa8..001298698d 100644 --- a/docs/website-style.md +++ b/docs/website-style.md @@ -11,83 +11,67 @@ We're still building out custom CSS functionality with the MyST engine. Follow and comment on the issues linked below to help us improve it! ::: -## Use content blocks +## Defining a Style Sheet -:::{warning} CSS class support is very limited -Currently, you can only use CSS classes that are pre-loaded by MyST from Tailwind CSS, or defined in the HTML theme (see below for examples of both). -See these issues to track some of this: +The [default MyST website themes](#default-web-themes) support bundling a custom [style-sheet](https://en.wikipedia.org/wiki/CSS). This can be used to introduce custom CSS styling to your website. To include a custom CSS file as part of your website build, you can define the @template-site-myst-book-theme-style option, e.g. -- Defining your own CSS classes: https://github.com/jupyter-book/mystmd/issues/857 -- Load extra Tailwind CSS classes when they're used on a page: https://github.com/jupyter-book/mystmd/issues/1617 +```{code} yaml +:filename: myst.yml +:linenos: +:emphasize-lines: 3 +site: + options: + style: ./my-style.css +``` + +For example, the style-sheet could contain styling for `em` elements nested below a particular `text-gradient` class: + +:::{literalinclude} public/style.css ::: +## Adding CSS Classes + +The intended way to apply custom styling to your MyST website is to use CSS classes to connect your content to the style sheet. There are several ways to do this. + +### Use content blocks + [Content blocks](../blocks.md) allow you to attach arbitrary metadata to chunks of content. You can attach one or more CSS classes by defining a `class` attribute for a block. For example the following: -```md -+++ {"class": "col-gutter-right"} -Right-styled +```{myst} ++++ {"class": "text-gradient"} +This is _emphasized_. This is not emphasized. +++ -Normal-styled +This is not emphasized. ``` -Results in: - -+++ {"class": "col-gutter-right"} -Right-styled - -+++ - -Normal-styled - -## Use `div` and `span` elements +### Use `div` and `span` elements You can attach classes directly to [`div` and `span` elements](#div-and-span). {myst:directive}`div` and {myst:role}`span` are analogous to their HTML counterparts. Unlike their directive/role, the HTML elements can also be given `style` options, e.g. -
Here's my div
+```{myst} +
Here's my div
-Here's some Span content - -## Add CSS classes to directives +Here's some span styled content +``` -:::{note} Not all directives support the `:class:` option -If you wish to attach classes to a directive that doesn't seem to support it, please [open an issue](https://github.com/jupyter-book/mystmd/issues) -::: +### Add CSS classes to directives Many directives and content blocks have a `:class:` option that can be used to add arbitrary CSS classes. For example, below we add a CSS class to an admonition directive to snap it to the right: -````md +````{myst} ```{note} -:class: col-gutter-right -I'm on the right! +:class: text-gradient +I'm _very stylish_. ``` ```` -```{note} -:class: col-gutter-right -I'm on the right! -``` - -## Use the HTML theme grid system classes to position content - -The HTML themes come with [a grid system of CSS classes](https://jupyter-book.github.io/myst-theme/?path=/docs/components-grid-system--docs). -You can use these to position content according to the link above. - -## Use Tailwind CSS classes - -:::{note} Provide feedback -This issue tracks loading extra Tailwind CSS classes when they're used on a page: - -- https://github.com/jupyter-book/mystmd/issues/1617 -::: +## Built-in CSS Classes -You can use any [Tailwind CSS class](https://tailwindcss.com/docs/installation) that's loaded on a page to style your content. -See the Tailwind documentation for examples of how to do this. -If a class seems to have no effect, it is likely not loaded on the page by MyST. -Currently, it's not possible to customize which classes are included on a page (see above for an issue tracking this). +The HTML themes come with [a grid system of CSS classes](https://jupyter-book.github.io/myst-theme/?path=/docs/components-grid-system--docs), which can be used out-of-the-box to position content. diff --git a/docs/website-templates.md b/docs/website-templates.md index a50b913ef8..c940dbfad8 100644 --- a/docs/website-templates.md +++ b/docs/website-templates.md @@ -11,6 +11,8 @@ They are defined via the same templating system used for [static document export For the remainder of this page, assume that "theme" and "template" mean the same thing. ::: +(default-web-themes)= + ## Themes bundled with MyST There are two templates for MyST websites, a `book-theme`, which is the default and is based loosely on Jupyter Book and an `article-theme` that is designed for scientific documents with supporting notebooks. The documentation for this site uses the `book-theme`. For a demonstration of the `article-theme`, you can see [an article on finite volume](https://simpeg.xyz/tle-finitevolume). diff --git a/packages/myst-cli/src/build/html/index.ts b/packages/myst-cli/src/build/html/index.ts index 9daece8437..a30f5e77da 100644 --- a/packages/myst-cli/src/build/html/index.ts +++ b/packages/myst-cli/src/build/html/index.ts @@ -89,7 +89,8 @@ function rewriteAssetsFolder(directory: string, baseurl?: string): void { const data = fs.readFileSync(file).toString(); const modified = data .replace(new RegExp(`\\/${ASSETS_FOLDER}\\/`, 'g'), `${baseurl || ''}/build/`) - .replace('href="/favicon.ico"', `href="${baseurl || ''}/favicon.ico"`); + .replace('href="/favicon.ico"', `href="${baseurl || ''}/favicon.ico"`) + .replace('href="/myst-theme.css"', `href="${baseurl || ''}/myst-theme.css"`); fs.writeFileSync(file, modified); }); }