-
Notifications
You must be signed in to change notification settings - Fork 8
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 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 |