search

ioos / ioos-code-sprint

Information about IOOS Code Sprint activities.
https://ioos.github.io/ioos-code-sprint/
MIT License
8 stars 14 forks source link

Handle individual Code Sprints by year with persistent URLs #23

Closed mwengren closed 10 months ago

mwengren commented 1 year ago

It would be great to be able to build individual sites for successive Code Sprints (2022, 2024, etc). Ideally, URLs would remain static/persistent as well, e.g.:

Copy the approach that is decided on in: ioos/bio_mobilization_workshop#36?

Currently, the root GitHub page references the 2022 workshop, since this was the first one that used IOOS GH Pages for a web presence. That would probably need to be moved for upcoming years, anyway, but ideally the 2024 event could be located at a distinct URL and not be moved afterwards.

For reference: the 2019 event materials are hosted on glos.org: https://glos.org/2019-code-sprint/

MathewBiddle commented 1 year ago

Agreed! We haven't had a chance to tinker with the mobilization workshop materials. Hopefully we can get this figured out soon.

ocefpaf commented 1 year ago

:+1: while I like the "versioned" approach it does not really work for event, more for software documentation versions.

MathewBiddle commented 1 year ago

For the mobilization workshop, we decided to pin each year's materials with a tagged release and DOI https://github.com/ioos/bio_mobilization_workshop/issues/36#issuecomment-1398763013

I don't think that would work here, because we should still have references and the content from previous events to cite and give credit.

I'd like to spend some time figuring out how we do this. I am open to suggestions and contributions, however.

MathewBiddle commented 12 months ago

@ocefpaf @mwengren I would really like to figure out a nice solution to this. Especially as we're thinking about 2024, I would like to be able to link to 2022 materials and 2024 materials through different urls.

For the bio mobilization work that team agreed that the content will be continually updated and it was sufficient to use tagged releases for each year, and we didn't need to have each years materials discretely available. This is because the most recent year will have the most applicable information which might deprecate a previous years information. All this to be said, we had our reasons to not pursue the yearly url construct.

My initial, brute force approach would be to rebuild the entire website, nesting years as subpages and so on. This page https://ioos.github.io/ioos-code-sprint/ would be a generic IOOS Code Sprint landing page which references to the various year's materials as subpages. It will get tricky with the headers and so on, but it might be the simplest solution for now.

I think the trick will be how to separate the materials at the root directory for each year? For example, the agenda

Right now, I'm soliciting input on how we might want to pursue persistent urls for each year. I'll do some tinkering locally to see what is possible, but if either of you have solutions I'm all ears.

ocefpaf commented 12 months ago

My initial, brute force approach would be to rebuild the entire website, nesting years as subpages and so on. This page https://ioos.github.io/ioos-code-sprint/ would be a generic IOOS Code Sprint landing page which references to the various year's materials as subpages. It will get tricky with the headers and so on, but it might be the simplest solution for now.

I think the trick will be how to separate the materials at the root directory for each year? For example, the agenda

Those should probably be moved into the year's folde/subpage too.

Right now, I'm soliciting input on how we might want to pursue persistent urls for each year. I'll do some tinkering locally to see what is possible, but if either of you have solutions I'm all ears.

For the oceanhackweek we moved the past years into a folders that will get build as URL/YYYY but we left the root as the current page, even if it is duplicated. For example both https://ioos.github.io/ioos-code-sprint and https://ioos.github.io/ioos-code-sprint/2024 would be the 2024 code sprint. That makes the user experience and announcements a smoother. However, internally, we should always use the one with the year slug in the links.

I never build these pages so I don't know the details on the headers, etc. Let me know if you need some help. I can give it a try.

MathewBiddle commented 12 months ago

Okay, testing locally I can create a new directory for 2022/, update the config baseurl and repository and serve the page from the 2022 directory:

image

Now I'm wondering how GH Pages will know to build what's in the 2022 and 2024 directories?

ocefpaf commented 12 months ago

Now I'm wondering how GH Pages will know to build what's in the 2022 and 2024 directories?

I don't know the details for doing this with jekyll. maybe we don't need to do anything, with sphinx and other page builders, we drop the HTML in the directories and GH pages will do the right thing.

update the config baseurl and repository and serve the page from the 2022 directory:

Try to not update those. Leave them as root and create a draft 2024 page in the root to see how it goes.

MathewBiddle commented 12 months ago

Try to not update those. Leave them as root and create a draft 2024 page in the root to see how it goes.

I don't follow that last comment. Do you mean copy the content to the 2022/ and 2024/ directories?

MathewBiddle commented 12 months ago

Well that is failing miserably https://github.com/MathewBiddle/ioos-code-sprint/actions/runs/6909264590

I'll come back to this in two weeks.

ocefpaf commented 12 months ago

Sorry, I was not very clear. I thought that the just moving the headers would rebuild a "sub-header." However, while that may be possible with some jekyll/jinja magic, I believe we should consider making some permanent header and change some of the pages in the header to links. Right now we have:

  - registration.md
  - agenda.md
  - projects.md
  - videos-slides.md
  - resources.md
  - about.md

I think that registration and about could be the permanent headers, always pointing to root. With some tweaks we could also make projects, videos-slides, and resources permanent too, by linking to a root page on GH or in the docs that has all the years. We do that for OHW tutorials.

The agenda, however, is very specific and it would be confusing to link to a page with past agendas, so maybe that should be removed from the headers and made into a normal page linked from the main one.

What do you think?

MathewBiddle commented 12 months ago

Check out https://mathewbiddle.github.io/ioos-code-sprint/topics/2022/2022-04-25-01-compliance-checker-refactor/

From: https://github.com/MathewBiddle/ioos-code-sprint/tree/gh-pages-2022

Essentially, I added the date to the topic file names and updated the _config.yml to include the date in the url https://github.com/MathewBiddle/ioos-code-sprint/blob/3853f161949d7b89cc81a7aedcdbe6ae9b7563df/_config.yml#L39

We could add agenda to the _topics directory and adjust the name for each event?

ocefpaf commented 11 months ago

We could add agenda to the _topics directory and adjust the name for each event?

That is a nice solution!

MathewBiddle commented 11 months ago

I'll try to work through the proposal above to see where we get. I'm running into a lot of jekyll hiccups with the collections approach and links not working as expected.

MathewBiddle commented 11 months ago

this is waay harder than I expected it to be. It might be helpful to get on a call to figure out an approach as I keep running into roadblocks.

I tried to use the collections feature of jekyll to create yearly indexes of the project list. See https://mathewbiddle.github.io/ioos-code-sprint/topics/2022/. Main changes are at https://github.com/MathewBiddle/ioos-code-sprint/commit/2f93b1feab05c9404e86cb0d3545b0c73648bd62. That seems to work just fine and I can build on that for the 2022 materials.

However, I tried testing the system by adding a 'test_something' topic page for a 2024 topic https://github.com/MathewBiddle/ioos-code-sprint/tree/gh-pages-2022/_topics (see 2024-05-01-test_something.md) but that doesn't generate the 2024 page we expect at https://mathewbiddle.github.io/ioos-code-sprint/topics/2024/01-test_something.html. In fact, it doesn't create anything for that topic.

When I build locally, the _site/ directory doesn't have a 2024 directory either, only a 2022 one...

I think it has something to do with the defauls in the config, but I've tested a bunch of variations to no avail. https://github.com/MathewBiddle/ioos-code-sprint/blob/cb45c63e17418881be761cd7c1a2147d03c2477b/_config.yml#L46-L55

Note - if you're on my test page (mathewbiddle.github.io/ioos-code-sprint) the breadcrumbs at the top point to ioos.github.io, not mathewbiddle.github.io. Just keep an eye on the url as you browse about. image

As a last ditch option, if doing this within one repo is just too difficult, we could adjust ioos-code-sprint to be the home repo and create other repos ioos-code-sprint-2022 and ioos-code-sprint-2024 which would be referenced from the index at ioos-code-sprint.

MathewBiddle commented 11 months ago

I finally figured out how to make the 2024 pages.

There were some changes to jekyll between v2 and v3 related to serving pages with dates in the future: https://jekyllrb.com/docs/upgrading/2-to-3/#future-posts

To get it to work I updated _config.yml to enable future posts in this commit https://github.com/MathewBiddle/ioos-code-sprint/commit/da7c825d91c04c8b3e224a4ab044b679f896a323

Now we have a topics page, that includes all the topics https://mathewbiddle.github.io/ioos-code-sprint/topics/. We can configure that to separate each year and reorganize the tiles in a way that makes sense.

We have subpages for each year (which we can customize as well):

Next is to figure out what to do with the agenda and about pages:

I suppose we could set those up as collections as well?

ocefpaf commented 11 months ago

There were some changes to jekyll between v2 and v3 related to serving pages with dates in the future:

I'm not 100% happy with the fact that jekyll is forcing us to use blog-like date syntax for what is actually a dated-slug name :-/ Anyway, glad you found a way around it.

I suppose we could set those up as collections as well?

IMO, yes. We would lose past agendas in that setup, right? I don't think it is a big deal.

MathewBiddle commented 11 months ago

I fiddled with collections and think I have a way forward. TLDR; I've made a collection for anything we want to retain as the previous years materials and set the yearly url using permalink in _config.yml. https://github.com/MathewBiddle/ioos-code-sprint/commit/a998f5a02aa172c0c5fd53c7ecff71b2a43a215b

So, we have a main landing page: https://mathewbiddle.github.io/ioos-code-sprint/

Subsequent, yearly homepages:

Subsequent, yearly agendas:

Subsequent, yearly topic lists:

MathewBiddle commented 11 months ago

To create a new event for another year - simply create new markdown files in _agendas/, _homepages/, _topics/, and whatever other directory we would like to create to preserve previous years materials.

We would need to sort through how the pages will all link together on the website too.

MathewBiddle commented 10 months ago

I've cobbled together some processes to make yearly event websites. In short, defining the url structure via _config.yml, and defining some key variables in the Front Matter of the pages, the website can be divided into yearly pages.

Here is the major commit with most of the changes: https://github.com/MathewBiddle/ioos-code-sprint/commit/cd57a4b1213f0e297a34fdfdaa23bc17b4aabdeb

Please browse around https://mathewbiddle.github.io/ioos-code-sprint/ and let me know if you have any concerns with this approach.

If the page looks alright I can start a PR and we can move on from this.

:tada: Happy New Year! :tada:

P.S. There are some 'hidden' pages which I haven't linked to yet but could be referenced somewhere, eg. https://mathewbiddle.github.io/ioos-code-sprint/topics/ (the header is all messed up but that can be disregarded for now.)

P.P.S. I'd like to make each year have a different color scheme, just to make it clear your looking at another site. LMK if this would help or just confuse folks.

MathewBiddle commented 10 months ago

See

ocefpaf commented 10 months ago

Looks great! It is an interesting way to use the dates/blog-post machinery in jekyll to mimic what would be "just a folder" in other static site builder :-)

I have only one minor nitpick:

image

The partial URLs there look odd. We don't have to write them in full if you disagree but, if you agree, I can send a PR to fix that.

MathewBiddle commented 10 months ago

yeah, I thought those looked a little odd. There's probably a liquid variable you could use instead of site.baseurl that would be prettier. Feel free to give it a look.

ocefpaf commented 10 months ago

@MathewBiddle what do you prefer 1 or 2?

Screenshot from 2024-01-10 16-05-15

MathewBiddle commented 10 months ago

From Wikipedia's guidance on linking:

Generally, URLs and domain names are ugly and uninformative; it is better for a meaningful title or description to be displayed rather than the URL or domain itself. For example, European Space Agency website is much more reader-friendly than http://www.esa.int/ESA.

With that, go with the first example.

ocefpaf commented 10 months ago

With that, go with the first example.

Done in https://github.com/ioos/ioos-code-sprint/pull/30