julia
julia copied to clipboard
JuliaLang
Julia's documentation ala VitePress
Take a look at the preview and test the navigation and search capabilities:
https://lazarusa.github.io/JuliaDocs/
I just wanna to share how the Julia docs could look like with vitepress. If this is something worth of consideration, please help 😄 (easter holidays are over).
Some issues.
- The last steps of deployment are really cumbersome and will require considerable time from my side to figured out.
- Some dead links (not many ~10)
- styling issues (colour, landing page, etc...). Specially landing page, I'm still not happy about it.
PRs for styling at https://github.com/lazarusA/JuliaDocs or here in this PR.
I think it is the box that is incorrectly scaled (pretty much my fault). While expanding the docs, I had written a custom div element to surround the docs with a border, but I think the margins for that were hardcoded.
We could take a look at the Documenter.jl reference div and adapt it for vitepress.
A typo here? -- "Julia's"
yeah, I changed all Julia's due to a parsing error at some point. This one is hard coded, hence once the automatic sidebar is correctly implemented, it should be fixed 😓 .
It does look nice visually! I'm sure there's many tweaks to be made, but it does look beautiful (to me).
Lovely!
It would also be nice to bump DocumenterVitepress to at least 0.1.0, the "every release is breaking" semantic is not ideal.
Not really sure why we have the package.json and .vitepress directory here? The build should be seamless (i.e. that you don't configure anything outside of the makedocs call). It should also not require any external dependencies to be configured (i.e. Node, which I think this currently needs?).
It is! The installation of Node here is purely so we can cache node_modules for efficiency. The .vitepress folder is also there for theme customization - without it, you get something like https://chairmarks.lilithhafner.com/dev/ (you can even have a hero page, but to style it you need .vitepress/theme/style.css). We could have this point to an external file through a field in the MarkdownVitepress struct.
I have a package.json file in that repo even though I don't do (or at least don't intend to do) any customization. Happy to accept a PR that deletes that file (provided the docs still build)
It looks nice at first glance, but I dislike how the information density is sooo much lower. E.g. comparing https://lazarusa.github.io/JuliaDocs/manual/documentation and https://docs.julialang.org/en/v1.12-dev/manual/documentation/ on my MacBook 15" I see maybe 60% of the actual content. All this extra padding and empty lines, etc. adds up, as does the low max-width that seems to be fashionable these days (removing it makes it a little bit better but still far behind the old).
Another thing is the low contrast, e.g. dark gray on light gray navigation menu :-(. Perhaps there are other "themes" available that avoid this pitfall?
My first test was to search for mean. Not only was https://docs.julialang.org/en/v1/stdlib/Statistics/#Statistics.mean not near the top of the results like in the current docs search, it didn't show up at all! For all my gripes with the current docs site, this VitePress demo seems like a major usability regression.
That is a good point @ToucheSir. It's been working better than the regular search for some searches, but I hadn't seen this before. I am assuming that Documenter.jl is able to customize its search index here, which we haven't done with DocumenterVitepress. @mortenpi may be able to elaborate more on this.
Vitepress also provides a bunch of search customization options which we can try to monkey around with in https://vitepress.dev/reference/default-theme-search.
I do think DocumenterVitepress version seems prettier, but I share the concerns about readability at the cost of visual appeal. Here's a comparison between the current PR, the PR without a limit on max-width, and the current Documenter docs.
While increasing the max-width is something I support, I think it really makes it so that paragraphs are easier to read. We lose a lot of information content because of the sidebar being duplicated as the navigation bar (as well as an additional "on this page" dropdown).
I do like the navigation bar. It makes it easier to jump to a different documentation section. My suggestion would be to replace the sidebar with "on this page". Something like the right sidebar on docs.fast.ai which doesn't draw significant visual attention.
Overall though, I think the ability for DocumenterVitepress to support custom containers (e.g. before/after style code blocks) makes it much easier to write pedagogically good docs. So in support of this effort broadly.
Like others, I agree that while this new VitePress gives a nice asthetic attractiveness, it is worse on functional aspects, such as information density and things being so spread out to look "nice". Let's please not forget: the documentation of a software is a technical document: you want to maximize functionality not aesthetics. For me this change in documentation style is similar to going from a typical scientific paper layout to the layout of blogging platform like Medium. Sure, the latter looks much nicer, but is it more useful?
In JuliaDynamics the compromise I've reach to make things look "nicer" while staying in the standard Documenter.jl output style was to just color the sidebar with a theme color.
One other thing I find problematic that was not discussed as much: All content of the left side bar is duplicated in the top bar. What's the point of the top bar then?
If, at least, it was having different levels of navigation, that would be okay, but even so, why have two "side bars" when you could have one...? Why split the navigation into two parts when you could have it at one?
This was something I learned when developing workshops for documentation, I learned it from a flyer design workshop, that pretty much said "information that is of similar type must be close together". My application of this in documentation is that "information that is the navigation bar must be close together".
The Git history is messed and it now contains hundreds of unrelated commits
