Skip to content

Conversation

@brianhawthorne
Copy link
Contributor

@brianhawthorne brianhawthorne commented Oct 2, 2025

Add material to the Developer Guide detailing how to build a static site against a local theme, and how to connect a step debugger to the node process.

@changeset-bot
Copy link

changeset-bot bot commented Oct 2, 2025

⚠️ No Changeset found

Latest commit: ec0d510

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@brianhawthorne brianhawthorne changed the title Document static theme development :blue_book": Document static theme development Oct 2, 2025
@brianhawthorne brianhawthorne changed the title :blue_book": Document static theme development 📘 Document static theme development Oct 2, 2025
@brianhawthorne
Copy link
Contributor Author

brianhawthorne commented Oct 2, 2025

@stefanv ping

Not sure what I did to get all the --config commits appearing in this PR... but it only shows the single developer.md file as changed (which is correct). Any suggestion about how to avoid this in the future will be appreciated!

@stefanv stefanv added the enhancement New feature or request label Oct 3, 2025
@stefanv stefanv force-pushed the document-static-theme-development branch from 15054c9 to 6b72c8f Compare October 3, 2025 23:36
@stefanv stefanv added documentation Improvements or additions to documentation and removed enhancement New feature or request labels Oct 3, 2025

The [`myst-theme` README](https://github.com/jupyter-book/myst-theme/) provides a more detailed overview of the components of that package.

A theme may be deployed locally for development as a dynamic theme server, _or_ a site may be statically built against a local theme. Development procedures will be different depending on which deployment scenario you are targeting.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
A theme may be deployed locally for development as a dynamic theme server, _or_ a site may be statically built against a local theme. Development procedures will be different depending on which deployment scenario you are targeting.
For local development, there are two ways to deploy the theme (AKA the website):
as a server, or as a static build. Development procedures are slightly different, depending on which approach you take.

I hope my rephrasing is accurate 🤔

Here, we could also add a short sentence as to why you might use which approach. E.g., something like: "The static build approach is typically used when..." where it might be "you need a React debug build" or "you want to emulate a GitHub Pages deploy" or ... ?

I just re-read the whole thing, and realized that matters are further complicated, because additionally you can build the theme into a JS package, or access the theme locally. It feels like, in this PR, we may be conflating the two axes: static/non-static build, pre-built or non-pre-built theme server.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants