Replacing Hugo with Docusaurus for the main site and unify docs under the same


(Robby O'Connor) #1

So currently we all acknowledge that the main site leaves a bit to be desired. @judywawira said that she looked at and found Docusaurus, a similar tool to Sphinx/ReadTheDocs, which was built by Facebook and uses React.

The big win I see is that we can have a blog finally, hosted alongside our docs…all under one site…I like this over having separate documentation sites per-project, hosted under GitLab Pages.

I have an immediate need to toss up some guidelines on how I ran Google Code-in, in preparation for the 2018 run, so that the admin team can be in agreement and we can have some nice docs on it. I am working with mentors from other projects as well to try to somehow come to some kind of s standard operating procedure for administering the program for a given FOSS organization.

Does anyone have any opposition to me taking this on migrating our site to Docasaurus?

(Saptarshi Purkayastha) #2

So are you suggesting that we are going to host our own site and not use Gitlab pages? I don’t see how Docusaurus is any better than Hugo or many other static site generators besides being built on React. Hugo has a lot of plugins/themes and flexibility. The reason I feel that the main site is in an undesirable state is due to very limited attention to it. I don’t think it is because of Hugo’s limitation.

Gitbooks is also there for documentation. If we aren’t using that, maybe we should just use the gitlab wiki or the hosted mediawiki.

(Robby O'Connor) #3

I’m not saying Hugo is limited – just saying that we can combine the sites into one. For example – babel uses Docusaurus. It’s one site instead of 3 or 4. This would still be hosted on Gitlab pages.

(Michael Downey) #4

+1 to trying to consolidate documentation into a section of the main site. Also +1 to trying to merge Gitbooks stuff as well.

-1 for using something other than the GitLab Pages supported builders (and more importantly, the most mainstream ones) such as Hugo and/or Jekyll. We want to make it easy as possible for folks to contriute documentation, even if via merge request.

While Sphinx may be more powerful, Markdown is more universally understood syntax for docs. FWIW…