Add KUBECON.md

[kingdonb]

This is associated with fluxcd/website#1804

It will not be published on the website before we merge fluxcd/website#1804

We can see that it works in the preview build, (but we will need to merge this one first before we can see it working in the preview.)

I don't see why we would publish this page any earlier than ~1-2 weeks before KubeCon at earliest.

But there may be no reason to hold it up, either!

[kingdonb]

Verified all the links in the new file work, except for this one:

fluxcd/community: KUBECON.md

(the file does not exist until we merge this PR)

[kingdonb]

It can be in a separate PR, or we can hold this one up and put it in the same PR, but the idea is this KUBECON.md will go in a filter list so changes to that one, or any of these files that are listed as external sources an update to those files will trigger an action in the fluxcd/website repo, so those changes trigger a build and are immediately reflected on the website after they merge:

https://how.wtf/run-workflow-step-or-job-based-on-file-changes-github-actions.html#run-job-based-on-file-changes-in-github-actions

We'll use this:

https://medium.com/hostspaceng/triggering-workflows-in-another-repository-with-github-actions-4f581f8e0ceb#:~:text=Set%20Up%20the%20Trigger%20Workflow,for%20triggering%20the%20target%20workflow.

to trigger the fluxcd/website netlify deploy job.

I think there is no third step, unless we decide that we want to add a workflow that we can update the GitHub Sites page and it filters down to this repo, then you can merge changes direct to the website just by clicking the "publish" button and you can skip the PR reviews, like you mentioned in case of some last-minute change that needs to go in immediately.

I had a look into Google Sites API, which was deprecated with the revamp in 2016. It appears to be surprisingly difficult to integrate externally with a Google Sites page now, unless you have "Sites Classic"

So setting up triggers on Google Sites publish "Receiver-style" that trigger GitHub Actions jobs might be tricky, or even impossible. But we can fetch it every 10 minutes and write a trivial diff-based function that will make that work, even if it has 10 minutes delay, at least nobody would be waiting for a PR review to publish something urgently.

I think it's compatible with these ideas, even if we want the Google Sites page to be the main target for our QR codes, we should not leave those details off the main Flux website. It's better if it's streamlined, I think the same content can be mirrored in both places and nobody will object.

[kingdonb]

I had some time to think over how that workflow will work, and how we can expand this.

We can add additional pages and scrape them in from a source, like Google Sites, and add them as additional pages under "KubeCon!" like the "Project" header that does not have a direct link target, and is only a parent in the navbar/menu entries.

I don't know how we can make this bi-directional. If someone is editing the content in a Google Sites page, and we are scraping it into this repo, then people cannot edit the content in Git. Unless we use some kind of pull-request flow.

There is no way I can think of to get content from Git into Google Sites, unless we can POST an html / markdown content into it directly. I don't think Sites supports this kind of automation, but we can do the reverse with a GitHub Actions scheduled job and simple Ruby script. That stuff is "Phase 2" and would be in a separate, follow-on set of PRs.

[kingdonb]

TODO:

• update the kubecon.md page with content from @mewzherder Google Pages site
• automate updating the kubecon.md page similarly (with a GitHub Actions workflow)

[kingdonb]

As we said we can iterate on this, I think we will see in the preview once it's incorporated into the main site, the image links do render. I just did a simple conversion of HTML to markdown and deleted a bunch of garbage that I don't think we need.

We can work out any formatting issues before merging:

• Add Kubecon page for KubeCon Paris 2024 website#1804

which will do the actual publish step.

[kingdonb]

We might need to fix some links so they do not refer back to the Google Sites page, mainly image references I mean

I think those will necessarily be PRs to fluxcd/website, so we can add the static image content there. We can combine that with fluxcd/website#1804 - I'll leave the image references intact here, we will work it out in the next PR so there is no hot-linking or cross site anything.

[kingdonb]

I found html2md: https://github.com/suntong/html2md#usage that we can use to script this and build the automation

# download from: - and parse into markdown, discarding the first 6 and last 13 lines:
wget https://sites.google.com/view/flux-kubecon-paris-2024/home -O kubecon.html \
  && html2md -i kubecon.html |sed '1,6d'|ghead -n -13 \
  > KUBECON.md \
  && rm kubecon.html
# ... the content of KUBECON.md is added to a pull request

This is the code that we will run in the workflow, I'm building a GHA file now that will let us use html2md in the community repo.

There is a branch now in the community repo, kubecon-automation, that shows the output of the script, it isn't a perfect match but it comes close. I will iterate on that script until we have it ready to merge, but that can be in a separate PR.

It only takes 2 minutes to hand craft one of these files, and we're probably going to merge from it 5 times at most, so I don't want to spend too much time on scripting...

Happily, someone has already written html2md in go and it looks nearly suitable 🎉

[kingdonb]

I did some testing of the workflow here:

• Ubuntu 24.04 kingdonb/community#2

(this is an example of the pull request that will be opened when the workflow completes)

The workflow itself is here:
https://github.com/kingdonb/community/blob/main/.github/workflows/update-kubecon.yaml

I updated this so we're not building any go, just using a release archive of html2md (that's very fast)

I'll continue testing that workflow in the repo fork until it's ready. 👍 LGTM

[kingdonb]

I think we can merge it all at once now.

The rest of the work will be able to be done on Google Sites, and in fluxcd/website#1804

[kingdonb]

Images are going to be a problem. As is the formatting around images. I can update the site references to use hard links so they are not 403, but we're going to have to invent some kind of system to classify them if we want them properly displayed.

I'm for adding css classes in the alt text which seems likely to be a good solution. I can't see anything likely to go wrong.

[kingdonb]

This script was super annoying to test as a GitHub Action, so I broke it out into scripts/

I added a DEBUG flag which you can set to avoid doing the setup for html2md, in case you run this script locally and already ran go install for html2md:

export DEBUG=1
./script/update-kubecon.sh

The script also can't be tested on macos without additional changes because sed is not gsed

I think what we'll do is take each of the three image slug placeholders I've added with this script, and turn them into shortcodes instead. Then we can invoke whatever html we want from the hugo templates, by calling into them with alt tags.

[kingdonb]

I'm going to work out the last few details related to shortcodes in the other repo then I'll come back here and mark this one ready for review. The script output looks satisfactory IMO, but we're going to have to do some link munging because Google Sites will not hot-link to my external URL even if I give it one. It keeps copying the image into the site instead.

So we just have to handle images a little bit carefully; I don't think it's a blocker but it might prove to be too much trouble.

We have to merge this soon though, as the URL is being used in a QR code at KubeCon.

[kingdonb]

I believe I figured out how to use shortcodes properly(ish) - I'm comfortable merging this now, I don't think the script will need more changes, unless we're adding more images.

The only thing that's going to need work now is the website repo - I've placed a CSS class on each image/figure reference, we should be able to see them in the site preview after this is merged. It's going to need a little bit of tweaking to make the CSS class do something, then we can merge fluxcd/website#1804 and make it live.

[kingdonb]

The only thing I'm not sure about:

\-

html2md seems to have made a bunch of these in the markdown lists of talks. I'm willing to bet that doesn't show up in the website when the markdown gets absorbed by hugo.

I didn't think there was any reason to escape these dashes, but html2md may know better.

I have tested the script a bunch of times, including in github actions workflow (at kingdonb/community), and I don't think it will break. 🤞

[kingdonb]

Need one approving review to merge this, @stefanprodan @mewzherder FYI

LGTM