Update Wiki

[vhyrro]

Wiki Revamp

If you have a keen eye, you'll notice that a lot of fluff has been removed from the README. This is to make the project less scary to newcomers and to reduce the feeling of heaviness from the plugin.

Because of this though quite a few important bits of info were lost (the minimal reproducible example, the philosophy section). Additionally, certain links in the wiki now also point to nowhere (as they used to point to the README).

This issue serves as a tracking issue for the "wiki revamp", aiming to be much more useful to newcomers with GIFs, explanations and more. I also plan on putting design documents and others in the wiki too!

[vhyrro]

Yes, I'm aware the wiki is half broken... I'll try to fix that tomorrow 😅

[R2robot]

Completely broken. Trying to follow links on the start guide redirects to the start guide with "you do not have permission to edit the wiki"

[wSedlacek]

A work around for those who are interested, append the last revision which had the page you want to the url ie /46d175046806ae70360787cf4db902c42de5030b to https://github.com/nvim-neorg/neorg/wiki/Clipboard-Code-Blocks/

https://github.com/nvim-neorg/neorg/wiki/Clipboard-Code-Blocks/46d175046806ae70360787cf4db902c42de5030b

Links on the page won't include the revision so you'll have to copy link and append it anytime you want to follow a link.
But at least you can still get to it.

Alternatively you can always clone the repo

git clone https://github.com/nvim-neorg/neorg.wiki.git
cd neorg.wiki
git checkout 46d175046806ae70360787cf4db902c42de5030b

[roland-5]

Wouldn't it be better to just create a separate wiki page at this point? Use an documentation generator application like mdBook and give the address nvim-neorg.github.io or nvim-neorg.github.io/neorg?

[vhyrro]

The issues with the wiki now are simply a result of the new luarocks integration. The documentation generator needs to also run a version of luarocks in order to extract data out of running modules. I tried fixing this yesterday but I need to provide some special compile flags for it to start working again.

[simonhughxyz]

Just a question, why not include the wiki inside the Neorg plugin itself?
Should the wiki not be part of :h Neorg-modules?
And the norg spec be part of :h Neorg-norg or something?

[vhyrro]

Wiki is now back online and working! @simonhughxyz I've considered this several times before, but I just find it nicer for users to navigate some prerendered markdown with clickable elements over navigating the documentation pages from within Neovim.

Once Neorg gets good enough at high speed navigation between notes then I can start considering moving the help pages over to Neovim directly :)

[simonhughxyz]

Wiki is now back online and working! @simonhughxyz I've considered this several times before, but I just find it nicer for users to navigate some prerendered markdown with clickable elements over navigating the documentation pages from within Neovim.

Once Neorg gets good enough at high speed navigation between notes then I can start considering moving the help pages over to Neovim directly :)

Why not do both? Personally I would much prefer looking at module help pages by doing something like :h Neorg-module-core-concealer

[vhyrro]

Both is also an option, but will take some considerable effort to implement (the docgen code is modular enough to support it, but we'll need a custom export backend for Norg).

I'm down to support such a thing, but we have many higher-priority things on our TODO lists :)

[vhyrro]

Wrote ~300 lines of markdown already (phew, only 1/5 of the way there). All of the changes are being done in the better-wiki branch.

I've started work on a from-the-ground-up tutorial for Neorg as well as a setup guide for Neovim beginners. Additionally I have plans to add a design decisions document, a cookbook for common neorg configuration and a philosophy section. Hoping to make Neorg super accessible to beginners who may not have heard of the term "organizational tool" before.

Also going through all of the modules and taking note which ones need better documentation. If anyone has ideas which modules' docs coudl be improved then let me know!

[vhyrro]

Some parts of the wiki are missing again, sucks. Seems like luarocks hiccuped or something as it didn't pick up our new dependency... interesting.

[noctopixi]

Yes, I see that some content has gone missing, or it's out of reach. For example, trying to open the Journal page displays the error: You do not have permission to update this wiki.

I agree that having the wiki built into Neorg would be great, since checking Github might not always be an option, or convenient. For example, I had to make do with the Internet Archive.

Thanks for your amazing work, I started using Neorg recently and I love it! <3

[vhyrro]

Wiki is now fully functional and back online!