-
Notifications
You must be signed in to change notification settings - Fork 75
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
Conversation
🦋 Changeset detectedLatest commit: 2f2eae0 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
docs/website-style.md
Outdated
```{myst} | ||
+++ {"class": "text-gradient"} | ||
This is _emphasized_. This is not emphasized. | ||
|
||
+++ | ||
|
||
Normal-styled | ||
This is not emphasized. | ||
``` |
There was a problem hiding this comment.
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
There was a problem hiding this 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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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); |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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"`); |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
Warning
Depends upon #1864 to add support for
class
on blocksThis PR adds documentation for the proposed jupyter-book/myst-theme#540