Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

💇 Add documentation on site.options.style #1873

Merged
merged 8 commits into from
Feb 27, 2025
Merged

Conversation

agoose77
Copy link
Contributor

@agoose77 agoose77 commented Feb 25, 2025

Warning

Depends upon #1864 to add support for class on blocks

This PR adds documentation for the proposed jupyter-book/myst-theme#540

Copy link

changeset-bot bot commented Feb 25, 2025

🦋 Changeset detected

Latest commit: 2f2eae0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
myst-transforms Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Comment on lines 47 to 54
```{myst}
+++ {"class": "text-gradient"}
This is _emphasized_. This is not emphasized.

+++

Normal-styled
This is not emphasized.
```
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will require a re-build of the myst demo package

Copy link
Collaborator

@choldgraf choldgraf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great thanks! I left a few comments and suggestions but feel like it's safe to merge and iterate on once the main PR has landed.

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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe share a link to the issue where we discuss adding support for user-given tailwind classes?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm holding off here because I think we ought to suggest best practice, and what that looks like is evolving? See my comment about e.g. myst style ./foo.css etc. :)

@@ -0,0 +1,5 @@
.text-gradient em {
background: -webkit-linear-gradient(#eee, #333);
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lol this is a ridiculous example to use I love it

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🪩 gotta funk it up


- https://github.com/jupyter-book/mystmd/issues/1617
:::
## Built-in CSS Classes
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a recommendation for how people could build a custom CSS file with scss or tailwind? Might just be an npm command they use, or there's always the web-compile GitHub package if that's useful (currently under executable books but we could move it if need be)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a quickstart repo for generating a custom theme here: https://github.com/jupyter-book/book-theme-tailwind-quickstart

We could improve this UX by folding it into mystmd. I wonder how far along that axis we want to go? Easiest would be to expose myst style that runs tailwind's CLI on a provided file. Or, we could perhaps have something that hooks into the site config and pre-processes the style file.

I don't love option (2) from an extensibility perspective, but perhaps e.g. @fwkoch has some ideas on that. One approach would be to define a new option-type, e.g. stylesheet that is like file but is pre-processed after copying.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels like a place where we can take inspiration from similar projects. Docusaurus has a SASS plugin and recommends using it for SCSS and SASS. Could we do something similar? As an author I almost never want to have to create a new theme, but I do want an expressive way to make modifications to an existing theme from the same repository as my content.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the long run, yes. We would need support for non-transform plugins (perhaps with lifecycle hooks) and/or the ability to patch the site config.

-webkit-text-fill-color: transparent;
}
```
:::{literalinclude} public/style.css
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did not think about doing that, great shout!

@@ -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"`);
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why did this work before?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It didn't but there aren't many options, so didn't notice.

@rowanc1 rowanc1 merged commit 92839fb into main Feb 27, 2025
7 checks passed
@rowanc1 rowanc1 deleted the agoose77/docs-style-sheets branch February 27, 2025 16:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants