# Problems with mkDocs Most of these problems are due to the nature of mkDocs beeing in python, which is not the "native" way to develop docs/sites for web. ## Customizability limits For example: - Expand more (i.e. on the starting page) Is done currently by inlining html into markdown. -> This breaks mkDocs features such as link-checking inside the html block. A better aproach would handle this at the framework level. There are a lot of these 'little' problems, that we cannot *control* when we keep using mkDocs. ### Unified stack If docs and website use a native web framework; That allows us to build the best customized user experience. We can build a snug fit for presenting clans features for all different user groups. - Allows to be maintained by the same (ui) people, without switching their mindsets - Allows full customization ; if choosen correctly ### Mobile Currently we have very limited possibility to optimize mobile ourselves: mkDocs drops features on mobile: - Table of content - Sidebar Navigation doesn't provide an overview ## Plugin system - Seen as beneficial in the beginning. The ecosystem is quite limited. Writing custom plugins is technically feasible; It requires more time, is complex and done in python. Which is not web-native. Say we want for example: - option search - markdown directives - custom components (i.e. "next button", "add service" button) - ...whatever we may want in the future These are not possible. Current solutions such as 'nuschtOS' also require a lot of time and break with the user experience, while also beeing sub-ideal for our use-cases. ## Problems with existing Plugins - openapi: renders into an iframe, rather than integrating with mkdocs navigation system https://www.neoteroi.dev/mkdocs-plugins/web/oad/ - plugins require to be packaged in nix. This is not a real blocker but note that it adds work. Trying out a plugin requires packaging first, even if its turns out as the wrong choice in the end. ## Missing scalability - simple edits lead to a complete rebuild of the site. In modern approaches reloads are instant because granular changes can be hot-reloaded leading to faster developer iteration cycles. -> Currently editing docs involves waiting to rebuild -> Future: This time will increase as docs grow Observed on my machine: INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 9.37 seconds INFO - [15:31:56] Watching paths for changes: 'site', 'mkdocs.yml' INFO - [15:31:56] Serving on http://127.0.0.1:8000/ INFO - [15:32:06] Browser connected: http://127.0.0.1:8000/ INFO - [15:32:07] Browser connected: http://127.0.0.1:8000/ INFO - [15:32:23] Detected file changes Lets: Fix a single chracter typo -> INFO - Building documentation... INFO - Documentation built in 9.31 seconds <- full rebuild, for any trivial change. INFO - [15:32:33] Reloading browsers INFO - [15:32:33] Browser connected: http://127.0.0.1:8000/ Lets do 100 link fixes. (I just did this amount on friday 10.03) Wait time: ~16 min. Time to make the change: ~1hr; ~25% waiting for rebuild. ## Stale Caching - People repeatedly report bugs that have been fixed alread. - SEO's cache our site for too long. -> Can probably be fixed somehow ## Navigation Cannot be customized - We are forced to decide between auto-dir and manual for the entire docs - Sidebar cannot be customized - Decide which sections are closed / open / selected by default - Hightlight new / important entries - Sections / Section Dividers / etc. This is caused by a deeper problem: with mkDocs customizations are and will always be hard