search

scrapd / docs

The ScrAPD project documentation
https://docs.scrapd.org
MIT License
0 stars 1 forks source link

Experiment with Hugo to generate site #5

Closed rgreinho closed 5 years ago

rgreinho commented 5 years ago

Issue Type

Current Behavior

We are currently using MkDocs with the Material theme.

Expected Behavior

While MkDocs works very well and we have a fully automated pipeline around it, the number of available themes is very limited. Besides they all look too technical-documentation oriented.

As a maintainer I would like to provide a site which could act as a landing page and a documentation site. Ideally we should be able to post articles as well, like a blog (for announcements for instance).

Possible Solution

Hugo is great for this task and has very good themes. The Syna theme seems to match all the criteria.

stp-ip commented 5 years ago

Hey happy to see the interest in using Syna. Wanted to check in and see, how it is working out and what general feedback is available and anything I could help with in the transition (when still on the table).

rgreinho commented 5 years ago

Hi @stp-ip! Syna looks very nice and has the features we were looking for.

However we stopped investigating switching documentation generator because Hugo + Syna is more involved (fragments, etc.) than simply putting markdown files in a folder like we do with MkDocs.

But I'll definitely be in touch if we reopen this issue!

stp-ip commented 5 years ago

Thanks for the feedback. Yeah we do our best to be simple, but flexible, which ends up being a bit more involved than feels perfect. We'll definitely work on simplifying use cases and default more things so it works out of the box more often.