Redesign site with solution that uses Markdown for content

[colinkiama]

Time for Zola to make a comeback.

Problems with current sphinx solution:

• Python may be installed but you need to install python pip
• pip doesn't let you install dependencies globally without an override flag now
• No built-in live server solution for rapid development. Contributors have to use their own solution
• reStructuredText is complex compared to Markdown. For a project that we need to rely on external contributors for content, we should be using the more simpler markup solution
• Sphinx takes a while to generate the website

How New Solution Will Be Implemented:

• Existing content can be converted to markdown using Pandoc
• Sphinx/rST-specific features can be added using Zola Shortcodes
• Will deploy the Zola version of the website on https://docs-next.vala.dev
• The Zola version of the website will replace the existing sphinx one on https://docs.vala.dev

[Tbusk]

How's this coming along? I know there are plenty of alternates to Zola that could work. JetBrains writerside has github action support for building project files and deploying, and they use markdown files for pages.

GitBooks opensource also has a build and publish option as well.

[colinkiama]

I've been occupied with other projects so I haven't been able to work on this. I'll probably be able to start working on this next year.

Writerside looks like a great tool however, it's a plugin that's only usable in JetBrains IDEs.

My concern with GitBook is that not everyone will be able to fully preview the site locally on their machine. GitBook have their own custom blocks like: https://gitbook.com/docs/creating-content/blocks/code-block

Also there seems to be issues with navigating between links with JavaScript turned off. (See: https://docs.elementary.io/develop)

---

Sorry if it seems like I'm being really picky, we're at a point now where the process of contributing to the Vala website is pretty streamlined: https://github.com/vala-lang/vala-www

It would be great to have a solution that is flexible, fast and allows you to start contributing to the site as fast as possible with the editor of your choice.

It has been a while so there are probably better tools out there nowadays (especially when it comes to internationalisation, it's a bit awkward to implement it in Zola): https://jamstack.org/generators/