Skip to content

Github Wiki Vs. Github Pages

steveri edited this page Jan 24, 2024 · 10 revisions

Currently we use Github Pages to implement our Aha wiki. But what if we used the native Github Wiki mechanism instead? Below are some of the tradeoffs, as I see them. Also, I have prepared prototypes so you can compare our docs as

Wiki Pages
Can edit and preview directly in github GUI via "wiki" tab in `aha` repo Can edit and preview directly in github GUI as files in `_pages/` subdirectory of `aha-wikipages` repo
When editing online, "save page" immediately takes you to updated wiki Yeah, not so much
Can edit locally but cannot preview online until pages are pushed to master Same
Resides in a separate but linked repo, reachable via "wiki" tab of the main `aha` repo Resides in a separate repo, else every update would also impact main repo
While browsing wiki, if you see a page you want to update, simply click "edit" button and do it While browsing wiki, if you see a page you want to update, it's a whole deal
Pages are pure markdown Each page needs a special header with metadata such as "title," "author," "layout," etc.
Can generate custom navigation sidebar e.g. adriantanasa/github-wiki-sidebar, creating-a-footer-or-sidebar-for-your-wiki Can probably generate custom sidebar but I don't know how (haven't looked actually)
Source files and wiki accessible via same url https://github.com/StanfordAHA/aha/wiki Source files and wiki are separate urls
https://github.com/StanfordAHA/aha-wiki-page,
https://stanfordaha.github.io/aha-wiki-page
Source file changes appear to update wiki immediately Sometimes it takes a minute for source file changes to propagate to the wiki (Pages) site
Clone this wiki locally