Github Pages Wiki replacement

[spessasus]

I was thinking if fluidsynth could migrate to a proper static page hosted on GH pages. (something like what I did)

Github Wikis have several disadvantages:

• Not indexable by search engines
• TOC has to be manually updated
• No search function
• Separate from the core repo tree. So if a PR changes something that was in the wiki, the Wiki has to be edited after.

My proposal would be using MkDocs/Zensical as they create really nice static pages with sitemap and search, perfect for GH pages.

I could create a migration PR, with automated workflow and everything.

What do you think?

@derselbst

[derselbst]

One of the huge benefits of the GH Wiki is that it's easily editable by anyone who has a GH account. No PRs, no digging through a repo.

I don't buy your "No search function" point. You can use the Github search. The other disadvantages are acceptable for me.

So for the moment I'd prefer sticking to GH wiki. But thanks for the offer and the pointer to Zensical - I have a private project that might benefit from it.

[spessasus]

Well, today I learned that GH search can be used to search wikis.

The "editable by anyone" point is valid, though Zensical has the content.action.edit button which points directly to the file that the user is reading. So the "digging through a repo" problem is solved. The edit_uri field also allows us to specify the github contrib address (e.g. https://github.com/FluidSynth/fluidsynth/edit/master/contrib/ which automatically forks the repo and opens the web editing interface.

But I understand your decision. If ever you change your mind, let me know and I'd be happy to help migrating the docs. I've found them very useful, esp. notes on SF2 and SF3 :-)