docsify the existing docs

[userdocs]

I was reading some stuff and i saw you had md files in the docs folder so a made a quick docsify version of them to use with pages.

https://userdocs.github.io/sftpgo/#/

You can see it's just a few files added to the /docs dir and some menu items

https://github.com/userdocs/sftpgo/commit/81fb77e15ba1a58a61b1d61745e9ca34b212ffa2

super easy to maintain and works well i think. Nothing ia really built with via pages and docsify renders it client side.

if you like it I can make it a PR.

[drakkan]

The docs looks good but many links are broken, maybe a dedicated repo is more appropriate. I'm not sure I have never used GitHub pages before

[drakkan]

Docsify is the lowest maintenance as you never build files but directly render the existing files client side.

The other options can be more fancy, like Docusaurus, but you build stuff around your files using actions and that could fail. Docsify can never fail in this sense as it's 100% client side rendering.

The navigation structure and organisation will end up being similar and portable to other solutions anyway.

So to me, as per the example, Docsify was the easiest way to take what you already had and turn it into documentation with the least disruption and 0 maintenance burden. That's it's real appeal.

ok, let's try to use it then

Can you show me what links did not work? I can't see any issues when skimming through.

https://userdocs.github.io/sftpgo/#/account

OpenAPI schema

https://userdocs.github.io/sftpgo/#/check-password-hook

checkpwd link and probably any link to the examples or to dirs outside docs. I use relative links because this way the docs are versioned, if you are browsing v2.4 you will see the examples for v2.4 and not the ones in the main branch (that might not work with v2.4)

[userdocs]

I will play with it and see. Though I don't think you can version the docs retroactively but possibly implement a solution moving forward. I'll see if there is an good way to keep your existing docs intact and apply a documentation solution at the same time.

[userdocs]

After looking I better understand the problems. I see now how your docs are tangled between the root level of the repo and then inside the docs folders. There is no clearly defined root and you have relative links like ../../docker/README.md that could be /docker/README.md because in that context it's relative to the repo root anyway.

After some thought I do agree that a total separation of the docs from the repo would make sense. For a couple of reasons.

• The versioning part requires some pre generation via scripting/workflows to and still needs links changed. It's the real issue, from my perspective, that requires separation and correct structure.
• Creating a functional site using one of the mentioned tools, prefer docs are structured under a single root and that all links set to that.
• Linking in some docs can then be changed to be relative to that top dir.
• Previous branches docs can be imported and tidied up. Luckily not a huge amount.

Then you can use the versioning support (which excludes Docsify for lack of support)

https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
https://docusaurus.io/docs/versioning

I understand what has been done as it makes sense for using only the repo. It worked.

But to commit to pages served site, I think total separation is better if you really want proper versioning for the reader.

Maybe a new repo?

[drakkan]

After looking I better understand the problems. I see now how your docs are tangled between the root level of the repo and then inside the docs folders. There is no clearly defined root and you have relative links like ../../docker/README.md that could be /docker/README.md because in that context it's relative to the repo root anyway.

After some thought I do agree that a total separation of the docs from the repo would make sense. For a couple of reasons.

• The versioning part requires some pre generation via scripting/workflows to and still needs links changed. It's the real issue, from my perspective, that requires separation and correct structure.
• Creating a functional site using one of the mentioned tools, prefer docs are structured under a single root and that all links set to that.
• Linking in some docs can then be changed to be relative to that top dir.
• Previous branches docs can be imported and tidied up. Luckily not a huge amount.

Then you can use the versioning support (which excludes Docsify for lack of support)

https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ https://docusaurus.io/docs/versioning

I understand what has been done as it makes sense for using only the repo. It worked.

But to commit to pages served site, I think total separation is better if you really want proper versioning for the reader.

Maybe a new repo?

Thank you for your testing.
Honestly working on SFTPGo is becoming a full time job and most people expect to use SFTPGo for free and also get free support.
Often I receive private emails with compliants when I close issues pointing to the support policy and these people generally don't even star the project and they pay for everything (Cloud Storage, VM instances, network usage etc.) except SFTPGo.
For example, as a way to support the project, I offer SFTPGo on the AWS and Azure marketplaces and it is by far the cheapest of similar offerings, but people just use their own instance (which generally costs more than SFTPGo), they install SFTPGo themselves and then they contact me for support (both privately or opening issues here).
In the last month I have lost some good sponsorships for no reason (basically SFTPGo works and so there is no need to pay for support), I'm not sure about the sustainability of the project in the long run.
My initial thought of making a good product available for free and receiving a small amount from all (or many) users is probably a dream, only a few really understand what it means to maintain a sw like SFTPGo, all the others have to be forced to pay for features not available in the free version or anything like that and this is a model that I don't like.
The project sponsors contact me directly and receive the explanations they need if the documentation is lacking or not clear, therefore better docs will only make the life easier for people that use SFTPGo for free.
I'm still motivated to make SFTPGo better than similar commercial products but I don't want to invest any more time to make life easier for such ungrateful people, they don't deserve my time.

If you want to provide better docs, please start using your repository, I will consider merging this work and/or maintaining it in the future.
Thanks for understanding.

[userdocs]

I understand.

The main reason I think a new repo is better here is just for not having to backport changes to the branches that are required in main to make it work in /docs.

I'll make a working example of a dedicated repo docs and we can see how that goes as this means your existing structure is left intact and nothing breaks, no drama.