Sustainability playbook space

[virginiascarlett]

I would like to start working toward getting a "sneak peek" or "preview chapter" of the Sus PB onto the web sooner rather than later, or at least in a deploy preview link I can share. Even if I don't deploy or even push it anytime soon, I'd like to at least create a branch where I can chip away at it on my local computer. What's your vision for where the Sus PB will fit into the website?

[LauraLangdon]

If it were totally up to me, the playbook would be part of the existing resources on the site, with the playbook bit able to be exported to pdf and read that way for those who prefer that. If we didn't have the existing site I'd use Jupyter Book, since it's a configuration of MyST that's optimized for acting like a book, but since we do I'd configure the playbook pages using the same principles as Jupyter Book applies to MyST (since it's just skin over MyST), but without actually being a Jupyter Book (since it's a MyST site).

I'd imagine it going something like:

1. Create oss-resources/playbook and an _index.md to serve as a landing/title page for the playbook
2. Use the "export to markdown" function in Google Docs on the current draft
3. Split the resulting md file into some rough chapters or whatever and make them their own md files (probably several recursive iterations of this step)
4. Add the files to the playbook directory
5. Do the frontmatter things that link the files up (like prev/next links) and the ones that make export to pdf tidy in case anyone prefers a pdf
6. Add everything to the nav

Although I guess I'd also add a step 0: paste this plan into a post on the MyST Discord and make sure there isn't a better way to do it 😁

[gjanee]

Example of a website-book that has links to PDF/eReader version, DOI, even ISBN: https://caltechlibrary.github.io/RDMworkbook/

[gjanee]

• End of school year: have basic framework identified, configured, in place, with basic structure laid out, templates, etc.
• End of summer: basic content at least sketched out
• End of October: all content done, ready for external review
• Send out for review November
• Incorporate feedback, publish by end of calendar year

[virginiascarlett]

Have we ruled out using a separate GitHub repository? I imagine if we're still using GitHub Pages and MyST, we could do playbook.ucospo.net or ucospo.net/playbook, if we just configure our DNS settings correctly. Pros: much easier to organize ToCs and PDF export in MyST to provide a simpler user experience. Cons: Need to maintain the GH Pages, MyST, and GH actions stack in two places (or use a submodule, which may not be worth it).

[gjanee]

I would absolutely think you want this in its own repo, I can't imagine it any other way. Not sure what maintenance you're referring to. In my experience using Quarto, it just works, there is nothing extra to do. Is MyST different?

[virginiascarlett]

Update: I asked around in the MyST discord; the solution used by the JupyterBook team is described here. We can't copy their protocol exactly because GH Pages is not as good at redirects as Netlify is, but I think we can easily set up a new repo with the domain ucospo.net/playbook. Based on that blog post, it looks like we can configure the new repo to inherit certain assets from the main website.

Somebody suggested another possibility would be to swap out the toc.yml file with a GH action so that playbook readers see a clean ToC, but I'm not sure how this works exactly, and it sounds a lot more complicated than the first option.

I'm going to proceed with creating a separate playbook repository and see how it goes.

@gjanee: By maintenance, I'm thinking about keeping the look and feel of the two sites consistent, and preferably also configuring them to use the same tech stack (the same version of MyST, for example), though the latter is less crucial.

[gjanee]

By "two sites" are you referring to the main OSPO site? Can see the desire/value in having a consistent look and feel, but tying the two together sounds dicey to me. Somebody will want to do some change on the main site and will have no idea of the impact on the handbook, and/or won't be able to update the handbook as well.

[virginiascarlett]

The link I am proposing is pretty superficial. The playbook will just inherit certain HTML assets, like the favicon and footer. The alternative is to copy-paste those images and code and maintain the duplicate files in two places. I like the inheritance so that, for example, if we get a bluesky account and Laura puts a bluesky icon in the footer, that change will be propagated to the playbook. But otherwise the sites will be independent.

[virginiascarlett]

And hopefully the fact that the two repos are in the same GH organization and running on the same tech stack will make it easy to find and manage both.

[virginiascarlett]

Major progress being made: https://ucospo.net/playbook. I'm using a makefile to grab assets from the core repo and copy them to my repo, as discussed in #315. I think this will be cleaner than the solution I linked to above. I just need to run make sync on my playbook repo every time the core repo updates its assets, which I don't expect will happen often.

The demo site is still rough around the edges (for example, About link in footer doesn't work), but I think I'm happy with the structure of the two repos. I am fine with closing this issue.