Hello everyone,

It appears that progress on the transition to a new platform is currently stalled. To facilitate progress, I propose the following course of action:

• Rename the current repository to something like "switch2osm-jekyll-arch" and archive it for preservation as a historical artifact.
• Create a new repository named "switch2osm" where the code from my existing repository (https://github.com/Andygol/switch2osm-mkdocs) will be transferred, either through forking or simple copying. Starting afresh on the mkdocs platform, we can then integrate it with Transifex to support translations and encourage broader community involvement.

If this plan seems viable, let's proceed with its implementation!

Firstly - thanks for all your hard work here!

If this plan seems viable, let's proceed with its implementation!

As @pnorman mentioned earlier, this PR tries to do about three different things at once:

• move from jekyll to mkdocs
• add support for translation
• content changes, including adding some new "vector tile" pages

Taking these one at a time:

I've had a play around with the mkdocs versions of the pages and it seems to be easier to set up, easier to customise and more flexible with regard to formatting than jekyll - it's definitely worth moving to mkdocs for those reasons. When I tested it it was easy to deploy as a static site, so I'd imagine @Firefishy wouldn't have problems setting that up (availability of time notwithstanding).

It's not yet clear to me how the translation will work. Is the idea that initially the site is deployed statically without "live" translation (but with just a couple of pre-translated language versions) and later someone sets up translations via a service such as Transifex? That's how I read the initial comment "If necessary, the translation of texts can be organized through the integration with Transifex (use transifex.yml)". I'm not familiar with how that would work, and it'd probably be easier (as @pnorman suggested to try and do one thing at once) - move to mkdocs, and add translation later. To be clear - translation into whatever languages people are prepared to support is absolutely something that we should be doing, but we do need to understand how.

It's clear that this site is already well overdue for content changes that cover vector tile options. The priority eventually will be "whatever is available on openstreetmap.org", which I believe is going to be based on https://github.com/pnorman/tilekiln , see openstreetmap/operations#1073 and openstreetmap/operations#565 . However, there are a bunch of other vector tile approaches that people are using right now that ought to be covered too.

Eventually (and this really should be a separate PR after everything's comfortably in mkdocs and we've decided how and if to do translation) I think we'll want a top-level split on both the "using tiles" and "serving tiles" sides between "vector" and "raster" (and possibly other approaches - e.g. for Garmin). If osm.org starts serving vector tiles based on the shortbread schema then lots of people are going to want to try "using tiles" and need to understand what is in and what is not in that schema. We'll also want to cover the "serving tiles" and "using tiles" approaches used by some of the current higher profile projects such as OSM Americana.

One problem with the vector tile pages in this PR such as this is that there isn't really the level of detail that someone who is new to the process can follow. Compare "You can use tools like osm2pgsql or imposm to import OSM data into a database" on that page with the equivalent instructions on one of the raster map pages. I've tried in the past to find something that isn't dependent on a proprietary service, can be self-hosted and is well-documented, and the best I've found is the documentation around tilemaker. In contrast, with shortbread I fell at the first hurdle trying to set it up, although things may have improved** since I looked (e.g. via inclusion in osm2pgsql-themepark).

Some of the other content changes (e.g. the links in the mkdocs footer) could probably benefit from minor tweaks, but I'm sure that'll be easy to do in an mkdocs-only PR.

** edit: a quick check suggests they have.

currently stalled

Note

the overall comments that prevent a more detailed review remain.

This has the same issue as the previous PR where it's mixing changing to MkDocs, adding translation support, adding specific language translations, content changes (e.g. new images), and contribution guideline changes.

In other words, it would be more actionable if single PR would not mix several big changes.

Would it be feasible to split it in parts?

One problem with the vector tile pages in this PR such as this is that there isn't really the level of detail that someone who is new to the process can follow.
…
** edit: a quick check suggests they have.

@SomeoneElseOSM feel free to contribute to https://github.com/Andygol/switch2osm-mkdocs

Mateusz and Paul, thanks for the advice on this PR. However, the problem is not in how it should be divided or organized, but in the global intention. For my part, I showed a working example (https://andygol.co.ua/switch2osm-mkdocs/) and concept (https://github.com/Andygol/switch2osm-mkdocs, https://app.transifex.com/osm-ua/swtch2osm/dashboard/#/). On the part of the maintainers, I expect certain steps towards its adaptation or a statement that this will not be done. In addition to this PR, I proposed an action plan (#248 (comment)) that only maintainers can perform.

• Rename the current repository to something like "switch2osm-jekyll-arch" and archive it for preservation as a historical artifact.
• Create a new repository named "switch2osm" where the code from my existing repository (https://github.com/Andygol/switch2osm-mkdocs) will be transferred, either through forking or simple copying. Starting afresh on the mkdocs platform, we can then integrate it with Transifex to support translations and encourage broader community involvement.

If this plan seems viable, let's proceed with its implementation!

PS
@grischard @Firefishy what do you think about starting a project at https://switch2.osm.org (go2.*, move2.*, run.* — anything you want)?

@SomeoneElseOSM feel free to contribute to https://github.com/Andygol/switch2osm-mkdocs

https://www.openstreetmap.org/user/SomeoneElse/diary/404191 is my first take on the level of detail required. Hopefully someone will be able to follow that rather than, say, "Make sure you have Node.js installed on your system".

That's far from the finished article though (and as mentioned above anything for the switch2osm site would be better with separate "creating vector tiles" and "showing the output for the user"). Just writing that identified a few rough edges in the existing documentation (see my recent PRs).

I'm not convinced that someone who "just wants to serve some vector tiles on their web site" would want to use a special web server just for that, whether that's VersaTiles' one or TileServer-GL (though of course there will be niches for both of those), so I went with Apache and "mod_mbtiles".

However, the problem is not in how it should be divided or organized, but in the global intention

"How to get from here to there" is key to the process. Something that looks nicer, might support translation in the future (but it isn't explained how, yet) and contains some new pages that definitely need further work is a really useful demonstrator, but isn't something that can be merged as a whole.

FYI 🔊

Here are, for your attention, two GitHub Actions that I recently added to my project:

1. .github/workflows/exctarct-en-lang.yml extracts the English locale from mkdocs.yml into docs/en/en.yml, which will then be uploaded by the Transifex bot (or any other bot) to the translation platform.
2. .github/workflows/update-languages-in-mkdocs.yml merges languages files (docs/uk/uk.yml, docs/zh-TW/zh-TW.yml, … etc) into mkdocs.yml.

Now the workflow looks like this:

• If there are any changes in the menu structure, the corresponding changes are made to the file mkdocs.yml.
• Action extracts the English locale and saves it to docs/en/en.yml if changes have occurred
• The bot of the translation platform (now Transifex) monitors changes in the repo and synchronises them with the platform
• Users on the translation support platform are notified of new changes and perform the translation
• As soon as certain conditions are met for a translation on the platform (completeness of the translation is at least a specified percentage, or certain material must be fully translated; reviewed; etc.), the bot creates a PR in the repo to merge with the current codebase.
• The PR is accepted by the maintainers (or automatically, depending on the repo settings) and the translated material is added to the website.
• To add a new language:
  • Users of the translation platform submit a request to create a new language section there;
  • The project administrator on the platform creates a new language section (or it is created automatically);
  • Users of the platform translate materials according to their priority;
  • The translated file with the localisation is extracted by the bot and through the PR or automatically added to the source repo;
  • The Action, when the locale file appears, automatically adds it to MkDocs.yml and the new language section shows up on the site
• Users of the platform gradually continue translations and materials are transferred by the platform bot through PR or automatically to the repo source. Materials that have not yet been translated will automatically be displayed in the default language.

Ready to use code you may find here — https://github.com/Andygol/switch2osm-mkdocs/tree/main. Feel free to contact me for assistance with migration.

You can get hands-on and see what's what on a working example https://andygol.github.io/switch2osm-mkdocs/

Based on this I'm okay with moving to mkdocs. Can you prepare a PR that does that without unrelated changes?

Any progress on this?

I recently updated https://welcome.openstreetmap.org/ to @Andygol new mkdocs version, it is a great improvement. I plan to change switch2osm to the mkdocs version soon if there is no push back.

It is likely that not all the mkdocs pages will have all the latest revisions from the jekyll site, I would appreciate some help syncing them up.

CC: @SomeoneElseOSM

@Firefishy Obviously this PR can't be merged as is (see #248 (comment) above), but if the problem content can be removed (and the translation questions answered, which can be done later once the process has been established for "Welcome Mat") I don't have a problem moving the current switch2osm content as is to mkdocs. I do have a work-in progress at https://github.com/SomeoneElseOSM/switch2osm.github.io/tree/vector_intro_01 but I can point the new content there at the new site.

@Firefishy @SomeoneElseOSM Latest synced with this repo content you may find here https://github.com/Andygol/switch2osm-mkdocs/tree/main

Latest synced with this repo content you may find here https://github.com/Andygol/switch2osm-mkdocs/tree/main

Thanks for merging those! It's missing the last couple of minor changes, but that's easily sorted.

More of a problem is that https://github.com/Andygol/switch2osm-mkdocs/blob/main/docs/en/serving-tiles/serving-vector-tiles.md still seems to be there. It's absolutely true that we need something about vector tiles but I think that that is actually a step backward rather than forward - it's simply not a set of instructions that you can follow.

If you have a look at https://community.openstreetmap.org/t/vector-tiles-are-deployed-on-openstreetmap-org/133008 and similar community threads you'll see that there's a fair bit of confusion on "how to get to vector tiles appearing in my web browser" - people aren't grasping the difference between schema and style.

A couple of "obvious starter" vector tile topics might be:

1. how to make a change to an existing style (perhaps one for Shortbread, since OSMF's demo vector tiles are in that schema).

2. how to generate your own vector tiles in a schema (likely derived from an existing one), and then show those changes in a (modified) style.

These need to be in the "switch2osm style" - i.e. a set of instructions that you can "just follow" without doing extra web searching. However those are things to do independently of Jekyll/MkDocs (hence my comment above)

This has now been manually merged and the new site is live https://switch2osm.org/

@Andygol if possible please could you update the site per @SomeoneElseOSM comment here? #248 (comment)

@SomeoneElseOSM @pnorman Apologies for my bull in a china shop style of moving the switch to mkdocs forward. The switch is worthwhile in my view. If there are any outstanding issue or you guys would like with assistance with migrating any draft content across to the new setup please do let me know.

@Andygol We need to work out a clean process for translations. For now I'd be happy for translation contributions to be primarily via outside contributor Pull Requests. Simple and not over engineered is ideal.

I'd be happy for translation contributions to be primarily via outside contributor Pull Requests.

🐞 👇

Until the CWG and OWG agree on which platform to use for translation work, translators can create PRs themselves. To do this, simply direct those wishing to make translations to the instructions in this repo https://github.com/switch2osm/switch2osm/tree/main?tab=readme-ov-file#translation (see misprint above).

However, this requires some GitHub skills and knowledge of Git principles. Translation platforms take much of the ‘magic’ out of working with Git. They track changes in the source, notify translators of them, and, once the translation is complete, generate a PR to add the translation to the main repo. This significantly lowers the entry threshold for the general public to join in.

In my repo, I tested this possibility of working with Transifex and it looks great. I sincerely hope that the working groups will select and set up a project for this as soon as possible on the platform that will support the work on the translation of Switch2OSM content.

UPD. As long as the translation is planned to be done by creating the PR manually, the Actions that handle changes in mkdocs.yml can be deactivated.

@SomeoneElseOSM @pnorman Apologies for my bull in a china shop style of moving the switch to mkdocs forward. The switch is worthwhile in my view. If there are any outstanding issue or you guys would like with assistance with migrating any draft content across to the new setup please do let me know.

I spent a few hours and I think I've got all the content fixed so it's like it was before.

Until the CWG and OWG agree on which platform to use for translation work

I don't see any need for any OSMF WGs. Certainly not the OWG as there are no policy, budgeting or hardware planning issues. It's a question for the s2o maintainers.

I don't see any need for any OSMF WGs. Certainly not the OWG as there are no policy, budgeting or hardware planning issues. It's a question for the s2o maintainers.

I really hope this will be a solution that will work well for people who want to help out with translating the site's materials and keep everything up to date. 🤗

Certainly not the OWG as there are no policy, budgeting or hardware planning issues

ICYMI switch2osm.org is served by OSMF

https://github.com/openstreetmap/dns/blob/edb1b4c2ca359f650c7f0e13d0dd2fef90e52d62/src/switch2osm.js#L1-L14

https://github.com/openstreetmap/dns/blob/edb1b4c2ca359f650c7f0e13d0dd2fef90e52d62/dnsconfig.js#L252-L255

ICYMI switch2osm.org is served by OSMF

Yes - but ops would only be involved if updating translations was something that happened on the OSMF servers, rather than something in this repo. The deploy process is to run the container "ghcr.io/switch2osm/switch2osm:latest", and translation processes I've seen wouldn't change that. I can't see any situation where the OWG would be involved.