This is super cool. I think MKdocs is perfect fit. I believe Docker also uses mkdos at the backend. Atleast they did when they were in their initial years. I personally use it to track my own markdown files and stuff.
On Friday, May 22, 2020 at 9:09:18 PM UTC+5:30, Martin Blais wrote: > > Thanks to the work of Kirill Goncharov (and Dominik Aumayr's predecessor > static codebase reference) the conversion of Google docs to HTML via > Markdown works quite well. The final product is really slick: > https://beancount.github.io/docs/. I think in terms of documentation this > is the sweet spot I was hoping for: sources in gdocs that makes it possible > to just go to a doc and start typing immediately (zero overhead to make > fixes or rewrite portions), and for anyone else to insert a comment or > suggestion, but with an output familiar for an open source project > (familiar web pages with text). What we trade off for changes managed via > commits and the associated history, we gain in collaboration and much more > resultant documentation (I never would have written this much otherwise). > > As part of the Github migration, another thing I'd like to change about > the documentation eventually is the conversion of links between Google docs > from redirects through my website furius.ca, to use some other more > permanent means of redirect. > > The history of it is that began to write the docs I wanted to have a way > to refer to them by name, and the Google docs addresses aren't > memorable (they include a long auto-generated "document id" root at > docs.google.com/document/d/). I created a redirect configuration rooted > at http://furius.ca/beancount/doc/<name>. This way I could send links > that were more or less self-explanatory and that I could remember, with a > well-known public name (e.g., http://furius.ca/beancount/doc/install), I > would just type them in without having to look them up while writing an > email. I pretty much consistently inserted such a link at the top of every > one of the documents below the title. This would also allow me to change > which document an existing link points to, a capability I did not have to > use very often, but which was handy the few times I rewrote some of the > documents, e.g. http://furius.ca/beancount/doc/export. > > Overall the system works well. Here's the problem though: my website is > generously hosted by friends in their web design & development company. > Occasionally - several times per year - there's a network configuration > change or an outage and my server is inaccessible, sometimes for 1-2 days. > This means the links also aren't resolvable (the server can't respond with > a redirect) and if you're reaching the docs through an email thread or on > the Google docs source, the links simply won't resolve. This isn't great. > In Kirill's HTML conversion the links look like they have been mapped: > https://github.com/beancount/docs/blob/master/index.json so they link > within the generated site, but it would still be nice to be able to send > links by name and not rely on e.g., the generated names of the markdown > files. > > I'd like to move the link root over to something hosted at Github so the > docs aren't reliant on my server, the future of which is unclear (I don't > have plans to remove it but I don't really need it either). I wonder if > it's possible to create redirects rooted at something like > http://beancount.github.io/<name>, http://beancount.github.io/docs/g/<name>, > or something like that. Maybe there could be a mapping to both the gdocs or > the markdown generated docs with the same name, e.g.: > http://beancount.github.io/docs/g/export -> > https://docs.google.com/document/d/1mNyE_ONuyEkF_I2l6V_AoAU5HJgI654AOBhHsnNPPqw/ > > <https://docs.google.com/document/d/1mNyE_ONuyEkF_I2l6V_AoAU5HJgI654AOBhHsnNPPqw/edit> > http://beancount.github.io/docs/m/export -> > https://beancount.github.io/docs/12_exporting_your_portfolio.html > Given the scope this project has taken, I could even register a short > domain name for this purpose (e.g. beandocs.io?). > > This is just an idea. I know how to do this on an Apache web server. > But can it be done on something hosted at Github? > > -- You received this message because you are subscribed to the Google Groups "Beancount" group. To unsubscribe from this group and stop receiving emails from it, send an email to beancount+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/beancount/28055b2c-7df9-424b-b816-0aff53bf12d7%40googlegroups.com.
