Hello, hope everyone is doing OK during this hard time and looking after yourselves and others.
I recently finished building an alternative docs browser - something that started off as Sunday procrastination (a way to more easily views docs and examples together, and avoid working on my own website), and since developed into a sort of hybrid markdown, code (w/ Nikola docs) and file structure viewer. I also added a simple file search (Alt + F), “See Also” links between files, and markdown editor.
Under the hood, the app is built with Nuxt, which is a Vue JS framework for rendering single-page apps both server and client-side, with the added benefit of having a static website generator.
When ran locally, the app mirrors file and folder structures defined in the
docs.config.js file. An API middleware reads the files and folders into JSON and syntax-highlighted HTML, so that when navigating to a page Vue will request its own API (ie. ?as=json / ?as=raw) to render the view. Finally, when statically generated all of this is exported as a recursive HTML structure, that can be upload to a standard LAMP / FTP server or Github Pages.
What’s nifty about Nuxt is that it also combines server-side rendering and client-side rendering when statically generated. So when viewing the initial webpage, it’s already a raw HTML webpage (good for SEO, if that matters in this case) - and once the JS is loaded, will request subsequent pages asynchronously with Vue (where the API-generated JSON is embedded as a payload within the HTML).
In the static site the Edit button currently links to a readme, but when ran locally it will toggle a
<textarea> that can be used to save changes directly to file via the API (for safety, this only works on .markdown files defined by docs.config.js).
<img> embeds should be fine - though there are some caveats such as trailing slashes changing relative
<img> urls on the initial page load, or unusual asset locations - easily fixed by editing docs or swapping locations.
The ethos though has been to ideally not edit or change anything to fit the app, so that it just renders what’s already there. Conceivably it could also be used as a documentation / folder / code browser for anything you point it at - configurable via docs.config.js.
For the OF-specific rendering, RegEx is currently used to parse the Nikola formatted docs into lists of methods and variables, so they can be more cleanly rendered into menus (currently a method w/ documentation is labelled pink in the right-hand menu, and gray without).
Any feedback, bugs-found or ideas at this stage would be great. I’m also keen to know more about how Nikola is used to generate the documentation (something which I didn’t touch in the process), and whether that could be integrated or improved on.
Thanks, and keep well!