Deploy documentation as a website at docs.versatiles.org

[MichaelKreil]

No description provided.

[MichaelKreil]

I'm not really happy with SvelteKit. Maybe astro.js?

[marcopixel]

If you are okay with using Vue I would be glad to help you with the website & documentation :)

You can check out https://docs.rainmeter.net as an example of my work, i've updated the design back in 2017 and I think it still holds up pretty well 😉

I would either recommend Vitepress or Nuxt Content. Vitepress is currently one of the most-used frameworks for documentation websites (made by the Vue/Vite team itself), while Nuxt is much more flexible regarding customization & layout of the website but requires a bit more configuration.

[MichaelKreil]

First of all, wow - thank you! Your help would be a huge asset!

I've been experimenting with ideas for the new website: what to include, how to structure it, and so on. There's still a bit of "pondering" to be done.
But getting the documentation up on docs.versatiles.org has become essential. I agree that Vitepress would be an excellent choice.
Do you need any information to get started? We could set up a call to go over any open questions, or if it's easier, you could start with a prototype and we can refine it from there... however you like.

Thanks again for your offer!

[marcopixel]

I'm fine with preparing a prototype first - if you want we could have a chat, hit me up via email and we can work it out from there.

Should we keep this topic in this ticket or move it to another ticket?
Also should the documentation be a seperate repo from the website? Or is it fine that it might get merged into the website repo instead?

---

Here's a rough draft of the sitemap / structure i've made today - nothing fancy but i've kinda wanted to figure out where stuff should go :)

Feedback welcome ❤️

• Guide

  • Introduction - Short introduction of the project + info about web maps
  • Getting Started - Quick start guide using it with MapLibreGL JS
  • Generate your own tiles - Guide on how to generate your own tiles (whole world or region)
  • Customize your maps - Guide setting up the frontend and styling the map
  • Deploy your own server/tiles - Deeper info about setting up a tileserver with nginx, caching, cdn, + other platforms like google cloud
  • Use your maps - Guide on how to use the maps in your own projects

• Docs

  • Overview - Similar to current overview but with explanation of each of the modules
  • Modules - Deeper dive into each module with additional API / Reference information
    • Generator
    • Server
    • Network
    • Frontend
  • Tile Container (.versatiles) - Info about Container & Specification

• Examples - Self-explanatory

• Resources

  • Blog - Optional, might be useful to inform users about news around the project but isn't really a priority right now
  • Roadmap - Might be useful to state the current status of the software + link to github project board
  • Release Notes - Can be just a collection of all links of the Github releases/changelogs
  • Community - Links to other platforms like Matrix/Discord/etc... + community-made stuff like plugins or implementations
  • Showcase - Self-explanatory
  • About Us
    • Team - Low priority for now, just here to know where to place it later on
    • Philosopy - Low priority for now, just here to know where to place it later on

[MichaelKreil]

Should we keep this topic in this ticket or move it to another ticket?

I moved it to versatiles-documentation

Also should the documentation be a seperate repo from the website?

I think there are several advantages to having the documentation on a separate subdomain (docs.versatiles.org). So a separate repo, I think versatiles-documentation itself, would be sensible.

Your draft site structure makes perfect sense. It might even make more sense than what we have so far.
And the maximum depth (level 1 - level 3) of the structure should be fine.

[stefanhuber]

Hi, not sure if you made already progress on the documentation site. I don't know about the vue-based approaches, however Material for MKdocs is basically just markdown and few yaml configurations. It is widely used also, e.g., the website of MapLibre GL JS is based on it.

[marcopixel]

Sadly i haven't been able to further progress on the documentation because of personal things...
I've made some initial progress on structuring here on my profile - you can use that as you wish ❤
https://github.com/marcopixel/versatiles-docs
https://marcopixel.github.io/versatiles-docs/guide/introduction.html

@stefanhuber
VitePress is also just Markdown + Configuration, i've chosen it because i've used it already in the past and it's really easy to adapt & expand with custom vue components (like tools or external libraries)

[MichaelKreil]

Any help is appreciated!

[stefanhuber]

I have setup a minimal version of mkdocs material as a showcase for further exploration:
https://stefanhuber.github.io/versatiles-documentation

The source code is here: https://github.com/stefanhuber/versatiles-documentation

I didn't change any markdown contents, in some cases images don't work etc. This would require a more detailed investigation. This page works well I think: link

As said this is a first minimal setup. Many further options are available like color, logo inclusion, social links, even API docs etc. If you think this is a path forward, we could discuss next steps...