Tech Stack

[dszidi]

We need to decide on a technology stack. IMO some sort of static site generator would be ideal. I am inclined to use jekyll since that would make it trivial to run it right here on github. Every merge can regenerate the site automatically. It will also make contributing content to the site easy as all anybody will need to know is some markdown. If we later decide to move to another static site generator for whatever reason, they pretty much all take markdown as source files.

For hosting, I understand there is a community member that is already generously providing hosting. Deploying the generated HTML and other assets will be a simple rsync away. If that hosting option ever goes away, deploying to github pages is also an available option. The trick will be to figure out how to pull in the API pages.

TLDR;

We use Jekyll and figure out how to automate pulling in the API docs.

[rmottola]

I usually prefer just plain HTML, being sceptic with markdown, more suited for something like Wiki. Main website is self-hosted indeed. It just publishes a git repository, it has been all setup and works fine now.

[dszidi]

@rmottola I can relate to your hesitance towards markdown. There was a time when I was also trying to avoid it. My concern at the time was longevity and I didn't want to invest a ton of work in markdown format only for it to become obsolete a couple of years later.. I have long since gotten over that as markdown has been around for a long time now and it is pretty standard fare these days. More importantly, it is what every static site generator uses these days and static site generators are the real value proposition here.

If we can just keep a collection of markdown files then we can later bounce between different generators as you like. They all produce static html files in the end so we can avoid PHP and CMS type systems. No authentication, no databases to maintain and the site performance is super fast. Just pick a generator that has the themes, templates and language you prefer and you're done. The workflow is much like PHP in the end, you just replace a running PHP interpreter with a build step.