Documentation pages for different dyne software

[Sakrecoer]

We started building an MKdocs for dynebolic that resides here: https://dyne.org/dynebolic The problem is that the theme doesn't match the website and it has an odd location.

What we need:

1. A way to allow contributors to write documentation in markdown.
2. The theme must match the website.
3. In some cases, the documentation might need to be pulled in from an external repo.

To make it easier to find things in the future, I think we should try to find a convention for docs location. Perhaps something like dyne.org/software/$AWESOMEAPP/docs ? I do find myself dreaming of a docs.dyne.org that would list all software and their respective documentation in docs.dyne.org/$AWESOMEAPP :purple_heart:

---

I don't know whether this docs system is something that should be coded with astro, or if it can leverage https://vitepress.dev/. The latter was mentioned by @puria in the standup of week 13 as a mean to consolidate our documentation and theming it, which sounds incredibly sexy.

Please advise. I love you!

[puria]

Why with mkdocs? all the stuff you mentioned is already in place with the site itself. you can edit .md. Crowd can send PR to change it. And you can have routing with subfolders alredy. You can alsso pull the docs from elsewhere (for this maybe I can give instructions). All of this already themed ans styled.

But probably you started a new project, because the actual system does not satisfies, you? If you know why does not satisfy you, please share so we can enhance the actual system, and make you mOAr happy 😽

[puria]

Please consider also that all the repo under the dyne's github organization, when deployed on github pages, will automatically appear like this:

github.com/dyne/repo-name => dyne.org/repo-name

[Sakrecoer]

Thank you @puria I don't know why mkdocs, but yesm the current system is perfect for pitch-pages and blogposts.

For documentation we need a lot of internal linking and some form of navigation specific to the documentation. New pages need to have metadata or be strcutured in a way that they can be added to this navigation. It's good practice to offer an overview of what the page contains (current page navigation) and it would be nice if it was somewhat easy for a freedomlance dyne to easily find where and how to correct errors or contribute missing pieces.

[Sakrecoer]

Please consider also that all the repo under the dyne's github organization, when deployed on github pages, will automatically appear like this:

github.com/dyne/repo-name => dyne.org/repo-name

I suppose this is what is being leveraged to render https://dyne.org/dynebolic But i didn't know about this system. Very good to know! Thanks!

[Sakrecoer]

I realize that now is probably not the time for this, but i can't get passed the idea of having a wesbite dedicated to dyne documentation, such as docs.dyne.org. The beauty i see in it, is that everytime a developer would have to look up docs for one piece of software, they would potentiall be exposed to all pieces of software...

Just noting for future reference. :purple_heart:

[jaromil]

For now I am following @puria 's advice and try to move everything into one place: our dyne.org website.

So for instance for dynebolic I will change dynebolic.md to dynebolic/index.md and allow to have other files besides which render as a subfolder in the url. These files will then be linked in the index.