peterdesmet
commented
3 months ago After discussion at the General Assembly, @mtrekels and I thought it better that the documentation website contains Markdown pages only (not the source on which they are based, which can be linked to). That will make it a lot easier to maintain the website (no clutter).
Doing so, it's better to name the markdown page (e.g. code-repositories.md, rather than code-repositories/index.md). It is easier to navigate and makes for clearer pull requests. Parent pages and child pages can still be grouped in a directory. Both approaches will automatically convert to the expected permalinks.
Finally, tags and categories are hard to maintain, so we should just use a search. This is not available in Petridish (#28) at this moment, but I hope to implement that.
All pages are currently in the root, but might be good to organize them better:
index.md), so all files related to a tutorial can be kept togetherAn alternative to pages are posts, which would allow to assign categories and tags (not available for pages). Posts however cannot be expressed as directories and have names that include the data, so their name changes over time, making it harder to track in git. There is also a good search interface available, so categories and tags might not be necessary.