Gitpages docs?

[datacurse]

What are your thoughts on making a documentation for the project in a gitpages format? I think it could make it seem more friendly. Right now it seems like im reading ancient scrolls with sacred knowledge. And there are several links with this info. It feels a bit unstructured. Im pretty sure if you just fed it to LLM it would give you a nice set of structured md files to put in a docs format

[datacurse]

I think to put it in other words, it would make sense to give information more iteratively. The current readme is overwhelming (for me personally). Usually projects/plugins give you barebone example and then put meat on top, so that you can pick what you want.

The simple example you made, i think, makes most sense to start with. And then in the docs you would show how to split installed plugins into categories and why you would want to do so, how to build different versions of config, how to add lazy loading, how to set up and maintain paq, etc.

[BirdeeHub]

I have tried to generate md docs from vimdoc automatically but it did not work, and likewise I have tried to generate vimdoc from markdown and it also did not work

So I settled on generating vimdoc straight to html.

I am open to doing any docs reformatting that seems good, but if there is information that is duplicated between in editor and website, it should be generated into the other format from whichever it is. The majority of the docs useful to configuring after you have a setup should be accessible both from the webpage and from in the editor.

All of said generation is done by this repo.

It generates html from the vimdoc using nvim itself, markdown from the utils/default.nix and utils/mkOpts.nix, and then calls pandoc on all the markdown ones.

https://github.com/BirdeeHub/nixCats-doc

If you can find a way to restructure the vimdocs such that they are more digestible I would be very happy, and if you can find a way to have them generate to a better format on the webpage I would also be very happy.

I honestly have no idea what digestible is because I know it too well, and have just done my best. I will continue to make small edits improving them over time, but I wrote a lot of info. Possibly too much. I dont know what to delete, what to move, what needs more, etc.

[BirdeeHub]

The way it is generated definitely contributes to the feel of ancient tomes of knowledge, being vimdoc on a webpage exactly as in editor, and I am open to changing that, as long as there are still some form of in editor docs at the end, and I dont have to maintain 2 copies of everything.

But also the content itself also feels like that, because there is too much prose at the start and not enough direct showing stuff, and the heading names are weird, with them all being grouped under :h nixCats.flake.outputs for the most part but the docs for the lua plugin is just :h nixCats and its own file

So a lot could definitely done just by reorganizing the vim-help files without even touching generation, in fact, generating them into a more rustbook gitpages style would require them to be reorganized first most likely.

[BirdeeHub]

Basically what I'm saying is, yes but it is a big job and it needs to be reorganized before we can rework how it is generated into a different style.

[BirdeeHub]

Also, definitely some of the things that are currently vimdocs dont need to be

For example the lsp one, the overlays one, the main install instructions one, etc..

Those can all be written in webpage format first, with no need to translate them back to vimdoc.

The only things that neeeed to be in-editor are the categories sections, the packageDefinitions section, the settings in packageDefinitions, an explanation of the main builder argument, an explanation of adding packages that arent on nixpkgs, and an explanation of the nixCats lua plugin

So, most of https://nixcats.org/nixCats_plugin.html https://nixcats.org/nixCats_format.html can be reworked, but still needs to be possible to get from inside the editor. Everything else can go on the webpage only and that would be fine

Although it would be nice to generate the module options, and utils set docs into vimdoc as well eventually, as currently I can only generate them to markdown and html

[datacurse]

ok, ill try to make some prototype considering this

[datacurse]

@BirdeeHub hi again, i made cursed docs for nixCats, all content is written by chatgpt. i took valtio docs as a baseline and slightly adjusted them. i could have spent more time making docs making more sense, but i think that i dont understand nixCats good enough to do them justice better than llm.

you will need to self host it, but it will probably just take a single docker file. i use coolify for that. to run the thing you need to:

1. go to /website directory
2. run pnpm i
3. run pnpm run dev

here is the repo, you are free to use the code however you want:
https://github.com/datacurse/nixCats-docs

[BirdeeHub]

Hey so, Ive given it some thought, I dont think I want to actually host it. I like the free deal I have right now and it works well, even if it looks a bit archaic.

However, I fully agree, it needs to be updated. I want to redo the format of the vimdocs entirely, and then find a way to generate them to markdown in a sensible way. I have some ideas, but I cant promise on when.

If I can do that reorganizing I can likely get them to become markdown in a sensible way, and I know how to generate that into gitpages style docs, and can then change the style of all of them to be more like rust-docs or something else my own.

The biggest thing that is needed to achieve that is reformatting the vimdocs, while moving a decent amount of content out of the vimdocs into webpage only.

However, I am not a good designer, and the format and some of the things you have written in the markdown are likely to be a helpful style guide for it. So, thank you for the effort you have put in so far.

[datacurse]

oh im not the good designer either, markdown was made by chatgpt, you can ask it to help when styling the thing haha

i see so you want to have this pipeline of vimdocs -> markdown -> gitpages, fair enough !

[BirdeeHub]

There are a ton things to generate markdown to html and I could make any of those use gitpages docs if I have markdown or maybe even json of the vimdoc that is somewhat reasonable.

vimdoc straight to html is also fine, but the issue is the I need to get the other tools which generate markdown and json to match whatever format that ends up in, so generating all to markdown first and then to HTML will yield most consistent styling compared to other options I think.

The issue is I want categoryDefinitions and settings docs to be available in editor as vimdoc, and there isn't tooling for autogenerating vimdoc from markdown that I have found that actually works in a way that yeilds readable vimdocs

So I would need to write them in vimdoc and generate the other way if I can, which means I need to rewrite them to be less like a book to fit the other format better so that I can make a generation step for those.

[BirdeeHub]

So, yeah the thing that has been holding me back on this is that, what is required is to rewrite and reformat the actual information in the docs first, before I can think about putting it into other formats. And thats a lot of work.

Its a lot of words, and every time an AI touches it so far it has mangled 90% of the info regardless of how much I seem to chunk it up so its not proved to be a useable approach to reformat it with AI. Maybe I could make a RAG system that could help with that, but by the time I do that I could have just rewritten them myself probably.

So, thats the current hold up. I need a weekend where I am free, and havent come up with a new project idea that is more interesting than rewriting docs.

[datacurse]

oof yeah i understand the ai part. well, all i can do is wish you luck xd