Use Static Site Generation

eXpl0it3r commented 1 year ago

The SFML tutorials (and other parts of the website) have been kept unchanged for a long time now. I see three factors that affected the contributions:

SFML has been relatively stable, so there's no need for a lot of changes
The website is built with some HTML and PHP intermixed, as such not easy to contribute to (especially if you want to preview it)
Having to provide both English and French versions might turn away people rather quickly

Using some form of Static Site Generation (SSG) which creates HTML from Markdown files, would lower the barrier to writing more content and also allow for prompting editing more directly, among a large selection of "modern" web features. However there are a few points that I see as important and wouldn't want to sacrifice for the sake of simplicity or "being modern".

Requirements

Generate a static site from Markdown files
- Markdown is the defacto standard for writing plain text content these days
- Needs to support including/storing of images
- Needs to support code rendering with syntax highlighting
SFML 2 tutorials need to support English and French
- There shouldn't be many changes and we already have them in both languages, would be a shame to waste that
SFML 3 tutorials will be English-only
- We don't have the French language expertise in the (active) SFML Team and it slows down every contribution
"Corporate" Identity is important, there's room to change certain aspects, but I don't want a complete redesign
- Just because the web/society/Silicon Valley/FAANG has decided on how "modern" should look like doesn't mean we have to give up our established identity. The web wasn't created to have every single website look equal.
The static site should be self-hostable, if possibile not exclusively hostable via Node.js
- Static Site hosts come and go, we want to build sites that last, to not be surprised by sudden pricing changes, rely on thrid-party availabilities, or send traffic to services we have no control over
- See also my post on "Build With Boring Technologies"
The site should remain navigable without JavaScript
- JavaScript can be used to create amazing things, yet our static website doesn't do anything complex and as such, shouldn't require a JavaScript-based navigation

Optionals

Preview PRs on something like GitHub Pages / Cloudflare Pages / Vercel / etc.
Supporting content tabs, so we could potentially display C++ and C# code in the tutorials side by side

eXpl0it3r commented 4 months ago

I've become a fan of MkDocs, especially Material for MkDocs. I'm trying a few things on a separate branch feature/mkdocs-material and decided to write down some of my thoughts here. Maybe someone else will have an input as well.

Documentation

After trying various packages and generating options, there doesn't seem to be a way to easily include Doxygen documentation, as such I'd currently recommend extracting the header & footer and use that similar to how it's done currently.

Navigation

Currently we have semi-hierarchical setup Tutorials and Documentations being listed under the Learn page, but their URLs are directly tutorial/ and documentation/. To achieve this, we cannot generate the navigation based on the file layout and thus need some extension like mkdocs-literate-nav.

Home
Learn
├─Tutorials
│ ├─3.0
│ ├─2.6
│ └─...
├─Documentation
│ ├─3.0🔗
│ ├─2.6.1🔗
│ └─...
├─FAQ
└─License
Community
├─Forum🔗
├─Wiki🔗
├─IRC🔗
└─Discord🔗
Development
├─Repository🔗
├─Issues🔗
├─Changelog
├─Contribution Guidelines
├─Code Style
└─Git Workflow

Design

Material for MkDocs of course implies the usage of Material Design. This goes against the branding requirement. My hopes is that we can use some custom styling to make it look a bit closer to the current "corporate identity". First however, I want to make sure we can fully cover all the features we want.

Material for MkDocs automatically supports light and dark mode, as well as respective switchers.

Preview

eXpl0it3r commented 3 months ago

I've hooked up Cloudflare Pages to the mentioned branch and the result can be browsed here: https://sfml.pages.dev/

eXpl0it3r commented 1 month ago

Instead of attempting a big bang migration, which due to the 400+ pages to create/edit is a massive task, I believe it's better to slowly integrate SFML 3 changes and keep the old & new setup in parallel.

In a first phase, I want to add new pages into the existing tree, meaning that for example SFML 3 tutorials live as static pages in the tutorials/3.0 directory, while the rest of the site is still served via PHP.

[x] Define how the MkDocs output is placed in the correct folders
[x] Create a navigation that leads back to the old site
[x] Consider how early links to the SFML 3 pages should be integrated
- https://feature-minimal-tutorial.sfml.pages.dev/tutorials/3.0/
[ ] Fix documentation scroll issue with id-tags

In a second phase, we'd replace the landing pages:

[ ] Write the landing pages (home, learn, download, etc.)
[ ] Setup URL rewrites for *.php files to "clean" URLs
[ ] Fix navigation on the old sites
[ ] Link to the old pages for the tutorials, documentations and downloads

In a third phase, we'd do a complete rewrite:

[ ] Update all tutorials
[ ] Update all documentations
[ ] Update all download apges

SFML / SFML-Website