Skip to content

Latest commit

 

History

History
58 lines (38 loc) · 4.57 KB

How to update the featured notebooks.md

File metadata and controls

58 lines (38 loc) · 4.57 KB
Raw

System overview

The notebooks from https://github.com/JuliaPluto/featured show up in Pluto's main menu! How does that work?

featured has a GitHub action that takes all the notebooks from main, runs https://github.com/JuliaPluto/PlutoSliderServer.jl to generate statefiles, and the output folder is pushed to the dist branch.

The files on this commit are accessible through the GitHub feature of https://jsdelivr.com/, for example:

https://cdn.jsdelivr.net/gh/JuliaPluto/featured@5a7c784/ servers all files from this commit: https://github.com/JuliaPluto/featured/commit/5a7c784

The special file https://github.com/JuliaPluto/featured/blob/dist/pluto_export.json contains links to all other files, and this is used by Pluto to decide which notebooks and categories to display, including their titles, images, etc. This file is dynamically loaded in by Pluto's frontend when you visit localhost:1234/. The URL that Pluto uses is specified in the frontend/featured_sources.js file. It looks something like:

export default {
    sources: [
        {
            url: "https://cdn.jsdelivr.net/gh/JuliaPluto/featured@5a7c784/pluto_export.json",
            integrity: "sha256-Tzznrgmk+NaIL2Spb784vKjDKPM0dOIUXbcvx/z6IBQ=",
        },
    ],
}

By editing this file in Pluto's source code, you can make it show another set of featured notebooks.

How to change the collections

Pluto's main menu shows the featured notebooks in multiple collections. Currently, this is "Getting started" and "Pluto and the Web". These collections are defined by this file: https://github.com/JuliaPluto/featured/blob/main/pluto_export_configuration.json

For each collection, we specify a title, description and a list of tags. All notebooks that match one of the tags will be shown in this collection. One notebook can be shown in multiple collections.

How to add/change a notebook

See https://github.com/JuliaPluto/featured/blob/main/README.md

How to update Pluto

An important part of this system is statefiles generated by Pluto + PlutoSliderServer on this repo. The Pluto frontend can only display a statefile if that file was generated with the exact same Pluto version: statefile structure is not covered by semver.

This means that when something changes in Pluto's statefile structure (which could be on every release), we need to regenerate the featured notebook statefiles using that new version of Pluto, before releasing it to the world. Luckily, we have an easy github action to do that:

  1. Take the most recent commit to Pluto's main branch, which you want to release. Copy the commit SHA.
  2. Go to https://github.com/JuliaPluto/featured/actions/workflows/UpdatePluto.yml
  3. Click "Run workflow", and paste the Pluto commit SHA in the box. Press the green "Run" button.
  4. This will run some Julia code that updates the package environment. When done, it will create a commit on featured#main with the changed Manifest.toml. (Example)
  5. Like any other commit to main, this auto-generated commit will trigger the Export action to generate the new statefiles. From this point on, follow the steps for "How to prepare a Pluto release".

How to prepare a Pluto release

Whenever you commit to main, e.g. when you add a new featured notebook, or update an existing one, this will trigger the Export action to generate the new statefiles. You want those new files to be used by Pluto's main menu.

  1. Wait for the Export action to finish, and a new commit is created on the dist branch. (Example)
  2. Copy the commit SHA of this release, example 5a7c784 or 5a7c78401281eecf9eb1503226173c87e99c8742.
  3. Go to Pluto's source code, then frontend/featured_sources.js, and edit this file.
  4. Change the jsdelivr URL to be "https://cdn.jsdelivr.net/gh/JuliaPluto/featured@5a7c784/pluto_export.json" where 5a7c784 is your commit sha.
  5. Run Pluto on Chrome or Firefox, and go to locahost:1234/. Open the JS console, and look for an "integrity error". In the error message, it will tell you the correct value for the integrity property in featured_sources.js. Fill that in, and refresh.
  6. You should now see all the new notebooks! Click on a couple of notebooks to make sure that they load correctly. Run one of the notebooks.