Idea for newer documentation site

Site Feedback
1

hi guys, I basically coded brainless php which works without any database, have search form and does not require any kind sort of setup. Basically its bunch of php files with css and js and what it does, it watching data folder for anything inside. when it see any markdown file named.md it will generate in browser on a fly html version. All seo friendly as well.

Whole ‘‘wiki’’ are coded in bootstrap so its responsive and any device friendly. From point of documentation all it needs it markdown files to be uploaded to /data folder and thats it, no coding no problem. Markdown in wiki support everything except the tables in markdown language eh but sometimes in future I might update it…however html tables (bootsrap) are working just fine. Also it support nested documentation… so if you will have for example:

/data
/data/bind/some.md
/data/apache/how-something.md
/data/custom scripts/some.php or some.sh
/data/index.md

It will create sort of menu on your left and searching filter is instant via names of the markdown files or folders or words inside of those. There is sort of option to have button on top of the page to view source which will show raw markdown file or any file as text without html in browser.

And in the end… Idea could be awesome… setup git repo where you will keep your all folders with markdown.md files… somewhere locally on your lan or perhaps private github or your own git solution, then setup wiki.sh script (I can help you with this) which will basically push new or any changes to documentation to git repo plus will refresh your data folder (sync with git repo) in one go. This way everything is trackable, safe and also when you need to put documentation into another wiki for example git wiki on github, you can recover all pure text markdown files from data folder or your existing git, or you can just download whole wiki and upload to diferent server, not even need to change single line of code :wink:

I think right now all docs are in drupal database… I can translate existing web pages to pure markdown and show you an example if you want, but please only if you would really consider this seriously

I might will need from you some links or just told me what to convert or use in wikis. No access to bd or server need it, all I would use is existing web documentation.

Let me know guys, also sorry for long post eh.

Thanks. G.

Edit: I’ve done sort of video for irc user Gizmokid2005 as he wanted to see… so I guess I can share… please keep in mind its raw and its just to show you how it would or could possibly looks like… In video there are my personal notes there but idea is same. See it here: https://youtu.be/-DxQuOdCNfo

2

also this tool can be used for writing something new… it works even offline so it can be run with python web server locally without internet https://cdn.topfreelancer.co.uk/editor/

it will give you some sort of idea how your final page as html will looks like… there is not tracking software no cookies etc… have look.

3

Looks really cool, but it’s not a good fit for us. I think I have a rough roadmap of where we’re going for all of our website tools (though it may change as I actually migrate data and try to integrate them all together). I’m trying to avoid PHP (nothing wrong with PHP, I just have never been able to get comfortable with it or enjoy it). Managing/generating/hosting the docs is literally the last/least of the problems I need to solve (it’s an easy day or two of work, no matter what I choose to put them in, as they’re already mostly written in Markdown and exporting pages in Drupal is very easy).

I’m much more worried about a good billing/commerce system (evaluating Spree and Solidus at the moment) and a good issue system (evaluating Zammad, Helpy, and RT); sharing accounts and single sign-on across all of those is the hardest part of it (well, that, and getting data out of Drupal in a sane fashion so it can be migrated). International commerce with recurring billing and notifications/email for thousands of users and tickets are both just such stupidly hard things to get right. These are the things that keep me up at night.

Right now, I suspect docs will end up in a Hugo or Jekyll generated static site. We don’t need a web-based editor, as we’d all rather edit Markdown in vim. And, I’m more comfortable with Go or Ruby than PHP, so Hugo or Jekyll will probably be a good fit (I already use Hugo for my personal sites and the new Webmin site I’ve been working in for like a year, but never quite got finished, is also built with Hugo).

I really want to stick with tools that are mature, have a lot of developers working on them, and are widely used by other projects like ours. Discourse was a no-brainer, since it’s become the de facto forum for OSS projects that have a large user base. The options for issue tracker and commerce aren’t quite as clear cut, and there is no clear leader, but I’ll settle on something soon after spending some time using the ones I’m evaluating.

4

@Joe sure it was only the idea :wink: