Rewrite: 11ty website

[mantoni]

This is a suggestion how we could combine per module README files with a "All-in-one" documentation page. The proposal uses eleventy to generate a static website using the README files as content.

For this to work, we need to add frontmatter to the README files. If this is something we want to avoid, we could alternatively store the information in a file called README.11tydata.json next to each README.

We could create a GitHub action to deploy this on GitHub pages, following the steps described here: https://www.linkedin.com/pulse/eleventy-github-pages-lea-tortay/

Run locally

1. Check out this branch
2. npm ci
3. npm start
4. Open http://localhost:8080 in your browser.

Closes #265

[m90]

I think the overall structure makes a lot of sense like this.

For this to work, we need to add frontmatter to the README files. If this is something we want to avoid, we could alternatively store the information in a file called README.11tydata.json next to each README.

I think that might be worth it, even if it's only for the aesthetics.

[mantoni]

A different approach could be to replicate the structure in site and keep the website entirely separate from the modules. This way the readme files can have different content than the website.

That would also give us more flexibility regarding the website design. What do you think?

[m90]

This way the readme files can have different content than the website.

I'm not entirely sure I understand this. Would this mean we would have a README in the module root and a totally different file in site? Or are they somehow (sym)linked, derived, processed or similar?

[mantoni]

Currently I'm using the readme files to generate the content of the website. We could, alternatively, generate the content from a set of entirely different markdown and template files. They don't have to be the same. The website could live in site and not use any content from the module folders.

My question is: Do we want the readme files to be different, maybe shorter, or do we want the same content anyway?

[m90]

We could, alternatively, generate the content from a set of entirely different markdown and template files.

How about we start by having everything in site but symlinking the existing READMEs into this directory up until the point we find that we need different content? If I understand it correctly this would also allow us to have frontmatter-less READMEs and define the foo.11tydata.json files in site?

[mantoni]

Interesting idea to symlink the readme files. I'll give that a try. 👍

[mantoni]

The symlinks with index.11tydata.json files work fine. Thank you for the suggestion!