Add support for loading user-defined CSS stylesheet

[agoose77]

Users often want to define custom styling (CSS, SCSS, or SASS) for their site. This allows them to do lightweight theming without needing to create an entirely new theme. It also allows authors to make page-specific styling for certain UI components etc.

Proposal

We should allow users to:

• Define custom CSS for their MyST sites.
• Allow users to write this as SCSS or SASS, including the use of variables.
• Ideally, allow for this either on a per-page basis (e.g. page metadata), or a project wide basis (e.g. myst.yml)

Inspiration

1. Point to an (S)CSS file from myst.yml. here's how sphinx does this
2. Add CSS directly to a page via HTML in the markdown (e.g. <style> tags)
3. Add CSS via frontmatter on the page or in myst.yml (e.g. a key like site.style: <scss rules to add to the page or the website>)

Related

• https://github.com/jupyter-book/mystmd/issues/857 would allow users to add classes that could be styled with this CSS
• https://github.com/jupyter-book/mystmd/issues/1040 would allow people to add style directly to a page
• Hugo transpiling SCSS docs)
• Quarto support for SASS variables.

Tasks and updates

• [ ] Automatically include e.g. myst-theme.scss

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[choldgraf]

I added a few ideas for how this could look from a user's perspective to the top comment

[AlexEMG]

That would be a great feature!

[cboettig]

Looking forward to this! In addition to CSS, it might be nice to be able to support SASS / SCSS transpiling into CSS. SASS supports things like variable definitions and many users may find it easier to write SASS than raw CSS (or modify any of the many scss themes). Other popular static site generators, like Hugo, have supported SCSS transpile on the fly for a while now (https://gohugo.io/hugo-pipes/transpile-sass-to-css/), and quarto supports SASS variables as well https://quarto.org/docs/output-formats/html-themes.html#sass-variables.

[choldgraf]

thanks for this @cboettig - I've included your links into the top comment of the issue and cleaned it up a bit

[sbooeshaghi]

Hi, I'd like to voice my support for adding the ability to reference raw HTML files in the myst.yml file. This would be valuable for my use case:

I maintain a tool documentation site (https://pachterlab.github.io/seqspec/) and have custom HTML content on a separate site (https://www.sina.bio/seqspec-builder/regions.html). I'd like to embed this custom content at a specific path on the main site (e.g., https://pachterlab.github.io/seqspec/regions.html).

The custom HTML contains an auto-generated table from a database, describing file format features documented on the main site. Colocalizing the docs and examples via MyST would improve user experience.

Ideally, I'd like to reference HTML files in the myst.yml file like this:

  toc:
    # Auto-generated by `myst init --write-toc`
    - file: README.md
    - file: docs/INSTALLATION.md
    - file: docs/UNIFORM.md
    - title: Examples # <-- requested additional feature
      children:
      - file: docs/regions.html
      - file: docs/reads.html
      - file: docs/assays.html
    - title: Documentation
      children:
      - file: docs/SEQSPEC_FILE.md
      - file: docs/SEQSPEC_TOOL.md
      - file: docs/SPECIFICATION.md
    - title: Tutorials
      children:
      - file: docs/TUTORIAL_SIMPLE.md
      - file: docs/TUTORIAL_COMPLEX.md
      - file: docs/USING_SEQSPEC.ipynb
      - file: docs/SEQ_PRIMER.md
    - file: docs/CONTRIBUTING.md
    - file: docs/CHANGELOG.md

This feature would significantly enhance my workflow and improve documentation integration.

[rowanc1]

This is super cool work @sbooeshaghi, thanks for sharing!

[rowanc1]

Thinking about the implementation of this:

1. we should keep this to the template and extend from that direction, which will allow different themes to treat these differently. For example, some themes may do tailwind or scss, or sass, plain css, or have no customizations, IMO that shouldn't be up to mystmd engine, but up to the theme. (e.g. asking for more than just a start command to be defined, and allowing for files in the template which is already possible).
2. There also needs to be a pass on adding class to every directive.

Adding classes to everything can happen right away. I would like a bit more discussion on how to add/compile css.

[agoose77]

Agree on both points.

We can refine (1) to see how hard SCSS vs CSS inclusion is, because SCSS covers all use cases with the caveat of needing tooling.

[agoose77]

Idea: support custom class on page in the frontmatter.

[labarba]

👋 can't wait for styling of JupyterBook v2 ... These days I'm adding Tufte-like styling to my individual notebooks, e.g. http://go.gwu.edu/engcomp3lesson4