Change website template?
Closed this issue · 7 comments
We have a very humble website here, but I'm not currently satisfied with the look and feel of it. The mkdocs-material framework was easy to set up, but the template is very limited. It really looks like a documentation website, which is neither necessary nor ideal for this project.
Do folks have suggestions for GH Pages frameworks/templates? I will also research this in the coming days/weeks and post my thoughts here. I assume we want to stick with GH pages, since we're all familiar with GitHub.
https://www.sphinx-doc.org/en/master/ would be a good starting point.
Examples:
Blosc: https://www.blosc.org/python-blosc2/getting_started/index.html
Zarr: https://zarr.readthedocs.io/en/stable/
Any static site generator should work fine:
https://github.com/collections/static-site-generators
Since most of the content is in markdown, so we would want a generator that works well with that.
Interesting, I didn't know that Sphinx could look like that, as it does in the Zarr and Blosc documentation. For some reason I always think of this template when I think of Sphinx. Sphinx uses reStructuredText as its markup language, rather than Markdown, which seems less than ideal. Sphinx also seems to have a lot of bells and whistles we don't need, like automatically generating API docs.
I was looking at Jekyll themes because Jekyll seems easy and popular, and good for blogs, not just documentation. This Jekyll template is my favorite of the ones I've looked at so far, but I don't know how easy it is to implement. Guess I need to just try it.
I'd be interested to hear if people have had positive/negative experiences with Jekyll, Sphinx, Hugo, Docusaurus, etc.
A large part of the choice here is how much one might eventually want to change the static site generators themselves. Github uses Jekyll because it is a Ruby based framework, and Github is coded in Ruby.
I think if you don't want the website to look like documentation, there's little use in going with a documentation-centered service. Jekyll was definitely the first thing that came to my mind.
However, Mark has a good point in that we should think about how the website will change and who is going to make changes. That perspective might show that we'd rather go with a less shiny, but easy to modify site. Unfortunately, I can't offer any experience with modifying a jekyll-based website.
https://imglib.github.io/imglib2-blog/ has been running with https://quarto.org/
I have been hearing a lot about https://vitepress.dev/ lately
Thanks for the suggestions. For now, I am going with Jekyll since it is a well-traveled path. I will continue to mess around with it and see how it feels. I still have much to learn, but so far I'm finding it easier and more aesthetically flexible than mkdocs-material.
Maybe if we find jekyll limiting, we can look into quarto, since apparently quite a few Janelians are already familiar with it.