search

kubermatic / docs

Documentation for Kubermatic projects
https://docs.kubermatic.com/
Other
15 stars 105 forks source link

Restructure the way KKP handles images #1654

Closed xrstf closed 5 months ago

xrstf commented 5 months ago

I think sharing images between KKP releases is a bad idea.

Ultimately I think it stems from the thought that images are assets like CSS and JS files, and so should be kept apart from the actual content. This made us and still makes us use static/img/ for all the images used by the KKP documentation. And since static/img/kubermatic/ is sooo far away from the content/kubermatic world, where things are orderly per release, why not ... you know ... have like a common directory[, man]?

Well...

KKP's UI evolves and so it should be obvious that even though you might think an image is totally common to all future KKP release, it totally isn't :D

To that end, this PR moves static/img/kubermatic/main to content/kubermatic/main/images.

This left static/img/kubermatic/common, my main nemesis in this PR. To prevent it from growing, I poured some acid on it and dissolved it: it basically only contained images for the applications feature and I copied/duplicated those into static/img/kubermatic/vX.Y for KKP 2.21-2.25 to content/kubermatic/main/images for main.

To prevent anyone from accidentally trying to share images again, I extended the filename verifier to ensure that no new directories are created in static/img/kubermatic and that new dirctories in the content directory must be releases. The existing images for existing KKP releases remain in static/, but at least it won't grow anymore. I mean, if desired, I can do this to all of the releases... and or products.

One of the biggest upside of common files is static, easy to write filepaths for images in the actual documentation. Now that images are in the content directory, every single image reference should begin with /kubermatic/<version>/images/... or be a relative path (highly discouraged, please do not begin to count ../ when refering to images).

To ease this, I added a image-render hook, which interprets a leading @ as "absolute URL to the current product's version", so you can write [alt text](@/images/ui/blabla.png) and get /kubermatic/main/images/ui/blabla.png.

However there is absolutely no reason or rule to say that all images must live in the images/ directory. If you have an image and it's not shared with anything, why force yourself to have to come up with a suitable name in the images/ directory? Just put the images next to your _index.en.md or have your own photos directory in content/kubermatic/main/reference/skiresort-hackathon/ and refer to it via [naked sales guy!](photos/sales.jpg).

But figuring out which of the existing images is shared between multiple pages (within the same version) and restructuring images accordingly is annoying and slow and worthless, so for existing images I just kept the structure. But:

! New content should feel free to put images next to their Markdown !

I also normalized the spelling of "catalogue" to "catalog" and provided some better link titles to make the navbar more compact. I also fixed the empty runbooks for 2.24/2.25.

embik commented 5 months ago

/approve /lgtm

kubermatic-bot commented 5 months ago

LGTM label has been added.

Git tree hash: 14133cd43a7f192e0ae1e59e04b65fa2468d9e93

kubermatic-bot commented 5 months ago

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: embik

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files: - ~~[OWNERS](https://github.com/kubermatic/docs/blob/master/OWNERS)~~ [embik] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment