Github Wiki Vs. Github Pages - StanfordAHA/aha GitHub Wiki
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 version or
- pages version (source files) (rendered pages).
| 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 |