Unrelated comment: I've been going through lots of the code, I appreciate how well commented it is and all of the links to relevant issues, I've come across a lot from @polarathene. Makes me want to work with this project more!

Also change a few hard-coded links to be relative where I thought it made sense.

Fantastic, thanks for catching those! 😀

I don't know how the description on docker hub is maintained, maybe that needs a manual update.
The github project description will certainly need a manual update.

I don't have rights to do either of those AFAIK. @wernerfred might?

Otherwise you'll need to wait on @georglauterbach I think, who is presently on vacation (and will hopefully make a best effort to remember they're on vacation, and wait until they've returned as there is no rush 😛 ).

Unrelated comment: I've been going through lots of the code, I appreciate how well commented it is and all of the links to relevant issues

We certainly try! 💪

It's something I tend to embrace a bit too excessively at times for the benefit of future maintainers (and sometimes future me who forgets 😂 ) as there is quite a bit of niche knowledge and decisions in the project.

I have gotten a bit more lazy with formatting merge commit messages on PRs, so git blame should help track down the relevant PR for better details / insights 👍

Makes me want to work with this project more!

We would absolutely love any help you can spare time for! ❤️

Contributing docs and assisting in issues as you've been doing is brilliant :)

Something maintainers often lack time for is improving the docs and UX (regarding what it's like for new users to get started).

There's the shell scripts that glues most of the project together, but I can't say that's particularly enjoyable 😅 or researching parts of the project to troubleshoot / improve something (scripts aside). I know I've sunk a tonne of time going down rabbit holes on niche topics just to fix some config settings 😛

Cheers, I'll wait for another approval for this change before merging.

Yeah, I believe you're right about the purpose of canonical links. Also the old versions of the docs will still have edge as their canonical versions unless we manually commit a change to those. Happy to add that to this PR or make another if that seems worthwhile.

There's the shell scripts that glues most of the project together, but I can't say that's particularly enjoyable sweat_smile or researching parts of the project to troubleshoot / improve something (scripts aside). I know I've sunk a tonne of time going down rabbit holes on niche topics just to fix some config settings

I have a strange fondness for bash haha. Before I found this project, I spent probably 50 hours trying to create something which was nearly identical to dms with bash, systemd, and systemd-machined.

Also the old versions of the docs will still have edge as their canonical versions unless we manually commit a change to those.

That's a pretty good point 😅

We could do that in a separate PR I think (keep that noise separate from main focus of this PR). (EDIT: As noted in 2nd section, this is probably not a PR we could review properly 😞 )

That reminds me of this issue with v11.1. Bit of a hassle (to build locally and adjust correctly) presently since it needs to be built like it would be via the CI for that tagged commit, but our CI workflow isn't setup for manual trigger of the workflow with inputs to support that (one fix).

I was working on enabling manual trigger in the CI workflow but didn't get around to finishing it.

At the same time, I'm kind of tempted to archive our older versions of docs at some point as we can't realistically support them the older they get.

Also I don't think the preview deployments are ever routinely removed either and I probably should look into sorting that out 😬

Happy to add that to this PR or make another if that seems worthwhile.

I'm a bit concerned about the diff size. It's probably not something I can review properly, and we can only trust ignoring large diffs from maintainers 😅

I could perhaps instead run a script to apply the change myself. (EDIT: This is probably the best approach)

Alternatively if we improve the workflow to support manual triggering of builds, it could be done that way too (probably not a good idea as running a newer version of the docs generator will probably break old docs with deprecated syntax / features, I know that happened at some point).

I have a strange fondness for bash haha.
Before I found this project, I spent probably 50 hours trying to create something which was nearly identical to dms with bash

Oh wow! You'd be very welcome to help with the scripts if you're comfortable 😁

The other two active maintainers are very good with bash, and we can all advise on the project if you have any questions.

I don't have rights to do either of those AFAIK. @wernerfred might?

Nope sorry. But that reminds me that we might need a list regarding all tools/portals we use and who is responsible/has permissions for what (github, dockerhub, netlify, ...)

Only linking to specific docs site might break in future when sites gets removed or moved between sections. That is something that won't happen with strickt versioned docs.

Hmm? Our docs are still versioned and you can link to them.

Recent contributions from @jrpear has introduced a latest alias to the current release (all handled via the CI when a release is tagged).

The plan was to default to directing users to those docs instead of edge, as we've received issues about users not paying attention to the version selector (which is understandable to miss when new to our docs), pulling :latest and getting confused by what the :edge docs say as those changes / features aren't yet released (v12 has been a rather long cycle with some bigger changes 😅 )

I can't recall much about that earlier discussion, perhaps it related to edge docs reflecting the master branch as we don't have any separate dev branch.

I think our users are more likely to encounter the mismatch with image registries and the default :latest pull experience, than they are with the git repo mismatching the default docs version we link to?

Looking at the edge docs we have a small tooltip that this is the latest documentation but not the latest stable one. Should we add a hint like this to the latest docs page as well stating that this is not the latest docs but the latest stable one?

AFAIK this is from refactoring that part of the docs during v12 by @georglauterbach

I don't think you meant tooltip (popover / hover), but the admonition (coloured boxed content) we have on the main docs page?

Once we release v12, the latest will also inherit that. It's a bit difficult to bring back to previous docs as they build off tags, we could inject it directly into the existing HTML content on gh-pages branch, but the markup/CSS may differ from earlier doc versions.

An easier fix is to remove releases after they're a certain age, simplifying the version selector to recent versions only. The markdown would still be accessible via git history on gh-pages, and running them locally to access in the browser should be doable easily enough with something like caddy.

Hmm? Our docs are still versioned and you can link to them.

Let me give an example:

You link to dms.docs/latest/some-site-a which is an alias for dms.docs/11.3/some-site-a

Now in v12 site-a gets moved to site-b

Someone later in time using dms.docs/latest/some-site-a would get a 404 whereas someone using dms.docs/11.3/some-site-a would still be presented with the initial linked (but now outdated) docs.

This even gets more complicated if not the site name switches but huge amount of the content is changed. Refs to this docs in old Issues or Posts will link to docs that might be completely out of context content wise.

Do you get my point or am i overseeing something?

I don't think you meant tooltip (popover / hover), but the admonition (coloured boxed content) we have on the main docs page?

Yes i meant that admonition

Once we release v12, the latest will also inherit that. It's a bit difficult to bring back to previous docs as they build off tags, we could inject it directly into the existing HTML content on gh-pages branch, but the markup/CSS may differ from earlier doc versions.

Thanks for clarifying, then i have no issue here. Just one further question. Will latest inherit the same box/info with v12? Asking because it states that edge is the default one but as i understand it it should be switched to latest then, correct?

This even gets more complicated if not the site name switches but huge amount of the content is changed. Refs to this docs in old Issues or Posts will link to docs that might be completely out of context content wise.

Do you get my point or am i overseeing something?

I understand that issue, but that isn't different to defaulting to edge, nor is it resolved even if we did change to manually updating URLs each time to the current release tag, as users may still do the same with edge doc links, or latest if we keep that around.

latest will be just as prone to the issue as edge, and I can see how that may be more prone to happening than edge would, but I have often seen this done with edge links when users are actually discussing released versions. I personally try to use versioned links when relevant but it's often convenient to just grab the URL forgetting what version you're on (in which case I'd end up with edge, and now latest, so nothing really changes - that's user error).

Will latest inherit the same box/info with v12?

• The version selector will have two entries for the latest release (latest + actual tag/version). Behind the scenes latest is just a symlink to the current release version docs folder.
• The admonition is not built dynamically and won't differ from edge docs. Presently it's hard-coded to edge and the description makes a mention of that, while this PR changes the mention and URL versions to latest, thus our edge docs will also reference latest in the admonition.

I think those were the answers you were after?

If you're still concerned about latest and would like a better solution, I believe I brought this concern up when we first introduced the docs.

Github Pages doesn't support redirects, but our preview service (Netlify) does. If we no longer used Github Pages (to publish, the gh-pages branch could still be the source content served), Netlify could redirect to the latest release instead, thus any latest URL should update to the current release version, and then any URL copied would be versioned correctly.

Only drawback is the host would change from Github to Netlify, breaking all the existing links (unless we kept serving them with a banner about the new home). Obviously not ideal, but that gets worse the longer we stay on Github Pages (which we've used for approx 2 years now?).

At the same time, I'd like to discard some older doc versions which'd have the same effect 😅 (on the plus side, with Netlify I have a 404 page that would at least better communicate to users about content being unavailable and direct them to the newer docs, GH pages last I checked didn't support 404 pages that well).

Since today is Nyepi on Bali, and I already spent a lot of time sleeping and being in the sun (since I am not allowed to go outside), I can warrant 10mins on GH even though I'm on vacation 😂🙂

The PR looks good! I'd stay with GH Pages for our docs because it is unlikely we loose the ability to show our docs this way due to cancelled OSS plans.

@jrpear we're always looking for contributors, moderators and in a best-case scenario, maintainers.

If you are interested in DMS, I'd start by inviting you to the moderators team first. This will give you the ability to adjust issues and PRs. You'd also have access to the private discussions repo. Thereafter, I'd add you to the maintainers team :)

Just tell me whether you're interested 🙂

Documentation preview for this PR is ready! 🎉

Built with commit: 9e1d7c6

PS: I will adjust the DockerHub README.

Imagine netlify cancelling their OSS plans then we are totally screwed

Vercel or another competitor would likely offer the hosting. It'd be fairly cheap to host ourselves too, but there is plenty of fallback options if that was a concern 😅

I'd stay with GH Pages for our docs because it is unlikely we loose the ability to show our docs this way due to cancelled OSS plans.

The main advantage of moving off GH Pages would be the redirect feature. I am incredibly stretched for time right now and doubt anyone else would want to sort that migration out, so GH Pages it is 😝

I'll merge this then, and raise a TODO issue about updating earlier docs (or alternatively archiving them away at some point).

Once again, thanks for the contribution! ❤️

@jrpear we're always looking for contributors, moderators and in a best-case scenario, maintainers.

If you are interested in DMS, I'd start by inviting you to the moderators team first. This will give you the ability to adjust issues and PRs. You'd also have access to the private discussions repo. Thereafter, I'd add you to the maintainers team :)

Yeah, I'd be happy to help moderate!

PS: I will adjust the DockerHub README.

Great! Do you have permission to update the GitHub project description too? That still links to edge.

Yeah, I'd be happy to help moderate!

You should have an invitation :)

PS: I will adjust the DockerHub README.

Great! Do you have permission to update the GitHub project description too? That still links to edge.

Done :D