ZK Documentation Github Pages - New site is up!

[mcDevnagh]

Our documentation is now hosted on github pages, thanks to @hugginsio via #387

Check it out: https://zk-org.github.io/zk/

A few things we should consider now:

1. Should we link to the https://zk-org.github.io/zk/ anywhere?

   1. I already went ahead and added it as the repository's "website":
      

   2. Add a link to the top of the README?

   3. Replace the links in the README?

      • this might not be a good idea, since the github pages only update with new releases, see

        zk/.github/workflows/gh-pages.yml

        Line 6 in 1471c6b

        - "published"

   4. Link it at each release, in the release?

2. Should the CHANGELOG be added?
3. Add a full table of contents to the README, or a separate file, linked by the README
   • as it stands, it's a bit hard to navigate (it feels like playing Six Degrees of Wikipedia)

[hugginsio]

Firstly, thank you Michael for collaborating with me to get #387 merged!

In response to this discussion:

• Could we add the link as the organization URL as well? I imagine most people who navigate to the organization page are looking for information about this tool.
• I think adding CHANGELOG as a page would be great, especially since it is very well maintained and lists upcoming features that aren't in a release yet.
• The Highlights portion of the README somewhat serves as a table of contents, but having a formal TOC would absolutely help with the website since we lack proper navigation menus right now. In Update documentation to restore GitHub Pages functionality #387, Michael and I discussed moving away from Jekyll to MkDocs (Material for MkDocs specifically) in pursuit of versioned documentation. This setup could be a lot better out of the box for project documentation, and would include search functionality and much better navigation. I will put together a proof of concept for a MkDocs refactor and share it here if there is interest in pursuing this.

[mcDevnagh]

Could we add the link as the organization URL as well?

done.

We'll wait on the Table of Contents until we know what we're doing with MkDocs

[tjex]

Awesome that the page is back up!

I'm wondering though, perhaps it's a better long term plan to have a separate repo for the zk website and docs?

The benefits then are:

• a dedicated place for working on documentation. Typically this speeds up workflows as well
• the option to switch to a more full featured static site builder such as astro in the future if needed (gh actions and workflows are more compatible and easier to manage then)
• separation of git history between documentation and code
• more steamlined, approachable and safer for users to contribute and update documentation
• a dedicated space for issues and enhancements to do with documentation (keeps the zk and zk-nvim repos tidier)

I've experienced these benefits while contributing to the docs site for actual budget

I'm also happy to take on the job of transitioning the documentation from the zk and zk-nvim repos to a zk-docs repo 🤚

[mcDevnagh]

that's an avenue I'm willing to go down. I think User facing docs certainly should be given a doc site like actual budget, and if a separate repo helps provide it, then great!
My only concern would be versioning. We would probably want to keep versions in sync between the different repos. Maybe my focus on versioning is misplaced, but I'm curious as to your input here @tjex

[tjex]

@mcDevnagh
In terms of "keep versions in sync"; Do you mean archiving, and keeping accessible, documentation for past version of zk?
So that users can access documentation appropriate for their (older) version of zk?

If so I would think making 'releases' of the doc site (which can run locally) for each major version update of zk should suffice?
So each major version, we make a release marking the final documentation state for that release, before moving onto any new documentation.

Other than that, Wezterm have these little "since version x" dropdown boxes to notify that certain feature are only available from a certain version.
https://wezfurlong.org/wezterm/cli/cli/list-clients.html

We could do something like that too, but might just make it a bit more overhead than necessary?

[mickael-menu]

For the documentation of a library, I would keep it in sync with the repo itself. For a user-facing software like zk, I think it's alright to have only the documentation of the latest version. Optionally we could archive the documentation and attach it to each release.

For zk-nvim it's a bit more ambiguous, as it's more than just a plugin but also an API. We don't have proper zk-nvim releases though, maybe we should.

[tjex]

ah yep, that makes sense.

So then loosely:

• developer / api documentation lives in the respective repos (e.g zk and zk-nvim) and is browsable via GitHub / within the repo.
• user facing software documentation lives in a separate repo and is accessible via github pages (perhaps also with documentation archival of previous releases).

Like that?

I'm still tempted by the idea to have the local documentation delivered as a self contained zk notebook within the repo. Just seems like too cool of a linkage between documentation and program/cause/philosophy/technique to ignore...
But maybe it just creates headache (eg, versioning the notebook db, although it can always be deleted and reindexed).

It's just so exciting when considering the possibility to browse documentation in neovim and have access to ZkLinks / ZkBackLinks / ZkInsertLink commands etc. It would make documentation reading and writing such a breeze 🤤

[mickael-menu]

Sounds good, I wouldn't bother versioning/packaging the db in this case. Zk can take care of generating it on the fly

[tjex]

Really dig this design aesthetic for a docs site: https://dlvhdr.github.io/gh-dash/

If people come across any other inspirations / designs / examples, post as replies within this comment :)

[tokisuno]

this would be sick. not a maintainer, just think it's cool.

[kabouzeid]

https://docs.astral.sh/ruff/

[jurica]

Out of the named ones I like gh-dash most, followed by ruff. While the astro docs also look quite good, they're a bit too colorful for my taste.

Another doc site I use on regurlar basis and like for the clean look and sublte color scheme is https://devdocs.io

[tjex]

Cool. I also like ruff. It's also a different framework (Mkdocs) than gh-pages (hugo). So we have some more directions of docs development. I'm leaning more towards a straight forward docs framework rather than a site builder (despite my previous Astro spruiking). Better to keep doc maintaining simple, meaning more free time to keep zk great.

[rmunoz]

Regarding mkdocs, I recommend having a look at material for mkdocs, which is a documentation framework built on top of mkdocs.

[tjex]

@zk-org/maintainers
So after a little investigation, I'm a bit torn between Hugo (gh-dash theme above) and mkdocs.

Hugo is seeming a bit overkill for our purposes imo. Mkdocs provides a much simpler and cleaner to manage.
I haven't managed to find a theme as crisp as the one gh-dash is using, but, the mkdocs community terminal theme achieves close to the same layout. The terminal theme is of course also fitting for us, but I understand reading monospace on the web can be testing.

It has a static sidebar by default (that scrolls out of view when you scroll down the page), but I was playing last night and implemented it as a sticky scrollbar (and made a pr, maybe they accept it). But worst case we could just manage our own fork of the implementation (if we like the theme in the first place)?

Cool thing is that it also has a sans font setting: https://ntno.github.io/mkdocs-terminal/configuration/palettes/sans-dark/

Otherwise, with monospace font: https://ntno.github.io/mkdocs-terminal/configuration/palettes/dark/

So, I'm thinking that if others also dig the terminal theme (monospace or not), we should probably go with that, just to keep things simple for now. There's not so much overhead for implementation of this, so if we find it's not cutting it down the track then we can scale up to something more beefy like a fully fledged like hugo / astro / 11ty / etc.

There is also still the material for mkdocs implementation and base theme, which is pretty nice. But doesn't have the same minimal / crisp / stripped back design that zk embodies. And is almost the same workload to implement as the terminal theme above, as it's all mkdocs under the hood anyway.

MkDocs also has built in static search box functionality out of the box too, which is really nice.

Thoughts?

[tjex]

Just came across the nltk docs page: https://www.nltk.org/

Also exceedingly crisp.

They're using the sphinx doc framework, which makes static pages, but also can generate man pages and has special functionality for code / api documentation (i think pulling comments, annotations, etc from source code).

Could be a nice option as it can be very simple (just paste in our current markdown documentation), but could be seemingly easily extended to give us more later down the track.

Their NLTK theme is available to use, but they recommend not to use it (🤷‍♂️) and to use the one they're based on instead: https://github.com/autophagy/insegel/

[hugginsio]

Good find with that terminal theme - it looks really nice in both offerings. It certainly fits the theme of the tool.

While it looks like there are some plugins that could help MkDocs export man pages, it would be nice to have that functionality out of the box with Sphinx. That could help keep documentation maintenance simple.

[jurica]

I agree, having a tool that's able to generates all required/wanted output formats without having to tinker around with plugins sounds like a big plus.

[tjex]

First play around (source code if peeps are interested). There's a bit of hackery going on, as Sphinx is based on rst documents, but via the myst parser, markdown can be used. So on the one hand it's a little quirky to get used to. But its the official supported way of using markdown instead of rst, so it's working well and becoming quickly pretty straight forward. And there are a good few nifty features built in.

Myst also allows the injection of rst syntax and features from Sphinx directly into markdown documents too.
Like callouts, which is pretty cool:

:::{note}
This will be rendered as a callout box.
:::

The current documentation we have has effectively worked seemlessly by copying them and the assets straight into the sphinx project. One thing is the div elements that are being used to center the images in getting started are breaking the images.

Removing the div images allows them to render, and because it's an actual static site, we have css, and Sphinx has a custom.css option which will override the themes css:

img {
    max-width: 85%;
    display: block;
    margin-left: auto;
    margin-right: auto;
}

So, that is one niggle, but otherwise we wouldn't need to change anything to get the docs site up. And we are barely using images, or need to rely on them too much. So it's not much overhead to get the images working at all.

I'll go through the paces of doing the same setup with mkdocs and see how that feels in comparison. But I'm pretty confident with the Sphinx option as a fallback.

One thing is it doesn't seem to have very good options for controlling how the items in the main side bar are generated.
Particularly nesting. It doesn't seem there is any nesting of pages possible... But I could very well be overlooking an option somewhere. But as it seems, each menu item is a document, and any 'nesting' is the titles from that document. This is also how it works with the default Sphinx themes. The menu item "test" is actually a file located at foo/test.md.

eg (same pages as above, but with html_theme_options = {"navigation_depth": 2}:

It's both a nice and annoying feature. It's fast for a user to navigate, but with a fair amount of documentation, the sidebar becomes suuuuper long...

Anyway, lets see 👍

[jurica]

Thanks for the summary, so far it looks like a viable solution to use sphinx.
I'm excited to read about your mkdocs try and the comparison of both.

[tjex]

So, had a bit of a play around with MkDocs. The two are really very similar, which is not a huge surprise. More of a surprise that Sphinx is still going strong considering how old it is and how new MkDocs is. But I guess, there really isn't too much extra spice to bring to static markdown documentation builders 🤷‍♂️

And so I reckon we go with Sphinx for these main reasons:

• It does everything that MkDocs does (sometimes in a slightly more complex way, but nothing crazy at all).
• It has some killer features built in the MkDocs (sort of, might) have via community extensions (like cross referncing 🤤, and also versioned docs are available, which potentially tackles the problem of API documentation along with the source code / releases)
• not to mention API documentation, direct links to source code, man page generation, latex / pdf generation 🤷‍♂️
• It has quite a few power features, but they don't need to be used.
• It's decades old and still going strong.

The only real potential snag I see is that markdown support has been patched on top by implementing the Myst parser. But that happened a few years ago, and it's seemingly super robust. I'm sure they did this out of necessity to stay relevant and compete with mkdocs, docusaurus, etc.

AND, I just found a very nice theme called, Furo, perhaps not as "crisp" out of the box, but it can for sure be made more crispy with a few tweaks (builtin user options and/or css tweaks). Hide some border lines, colours, etc.

But it has:

• scrolling left side menu, with dropdown itmes
• right local TOC bar
• dark/light mode
• really nice mobile adaptation
• support for "edit this page", making it smoother for users to fix up niggles in the docs
• and some other niceties

@mickael-menu , at this point I'd ping you and check back in, as my inclination is that the others will be happy with this choice (framework wise and also theme, as it's not such a huge departure from what we already felt was a good layout / design). Is it a go for you?

[tjex]

Went a little quite here, so I've pressed ahead with the direction mentioned above.

Tracking here in this repo for now: https://github.com/zk-org/docs

[mickael-menu]

Sorry I missed your ping. But that sounds and looks great!

[tjex]

@zk-org/maintainers

Alrighty, first working docs site is up 🥳: https://zk-org.github.io/docs/

The docs are also set up as a zk notebook, so all your fave zk-nvim / CLI tooling for writing is possible 🤓

Main question then is whether to keep the docs as a separate repo or not?

Pro:

• simpler to maintain (less files, cleaner docs git history)
• a nicer github.io url (potential to include zk-nvim docs in there too if needed later on)

Cons:

• need to manually manage versioning.
  One option would be creating a gh release in tandem when we create a zk release, perhaps this can be automated with a webhook?

Otherwise, any immediate issues / dislikes that I should fix? If not, and once we decide on mono-docs repo or not, I can finally put this task to rest!

[mickael-menu]

Nice, it looks really slick 👍

I would rename "zk-nvim" to "Neovim Plugin" in the sidebar to make it clearer for newcomers.

For the repository, I tend to prefer keeping the docs in the repo as it encourages updating the documentation in the feature pull requests and helps with versioning. But as you will probably be the one managing that @tjex, it's just a suggestion.

I wonder if it would be possible to keep the docs repository as a auto-generated repo and automatically copy the Markdown files of zk and zk-nvim when doing a release.

[tjex]

Thanks. Yep, that occurred to me too about docs being updated in tandem with PRs. Just happened in the last PR, and that's already such a bonus. I will implement it in the zk repo in the docs folder 👍

And will make that menu item change.

As for zk-nvim docs, will look at that once the readme stops sufficing. It could be functional enough to just give it its own sphinx instance, because sphinx also has an "inter-sphinx" anchor tagging feature. Basically you can link to certain headings / locations in documents from completely separate websites.

[tjex]

Completed with #453 : https://zk-org.github.io/zk/

Bit messy... but got there in the end.
PR for contributing.md describing steps for local building / other details to come.