GitHub wiki directories

Question

Does the wiki that installs with a GitHub repo support directories? Our wiki is cluttered with pages, and we are looking for a way to organize them better.

We tried pulling the repo, creating local directories, and moving things around, but when committed back, the wiki didn't pick up the changes.

score 65 · Accepted Answer · answered Oct 08 '12 at 17:18

65

I was having the exact same issue and tried variants of what you tried. Nothing stuck. Asked GitHub support about it and received a reply that essentially said "No, but we'll let the developers know that people are interested in this feature."

So the short answer is "No", and the long answer is "No, but maybe in the future."

answered Oct 08 '12 at 17:18

Collin M

1,143
1
12
16

9

The current short answer is "Yes". :) – Marco Jul 15 '15 at 10:19
2

@Marco After THREE years? GitHub really takes their user's request seriously! :| – trejder Oct 29 '15 at 14:28
15

Yep, still no, five years later – Lincoln Bergeson Aug 21 '17 at 22:13
1

Six years. Btw, heard people moaning about #Microsoft got the #GitHub back in the office. Today I've got too many disappointing and I think I can laugh them in face now. – DevOvercome Jun 05 '18 at 17:58
1

We can do it this way https://docs.gitlab.com/ee/user/project/wiki/ – Amrita Deb Feb 17 '20 at 13:00
2

@AmritaDeb Your link relates to _GitLab_, but this question was specifically about _GitHub_. – Collin M Feb 19 '20 at 10:01

score 31 · Answer 2 · answered Mar 28 '13 at 10:33

Actually, it looks like github added support for directories recently.

I was able to do the following:

Move an existing markdown file to a new directory.
Create a new markdown file in an existing directory (created in the former step).
Create a new markdown file in a new directory.

In all cases, the existing pages were still there and new pages were added.

The one constraint that remains is that your file names must be unique. If you have more than one file with the same name, only one of them will show up in the wiki (I'm not sure which.. ).

So basically, it just for organising your pages, but doesn't give you anything more. — Rene Pot, May 30 '13 at 09:14

Kevin Cox · Answer 3 · 2020-08-25T17:01:59.463

30

The GitHub wiki (aka Gollum) does use directories but not in the way you may expect.

The documentation on the Gollum wiki could use some work but this is what I have figured out mostly via testing.

All files appear in the root of the wiki no matter where they are placed in the repo.
_Header, _Footer and _Sidebar files are per-directory, but inherited if there is none present in a child folder.
File links can be relative to the source file (keep your files with your content).

So, if you want directories for namespacing you are out of luck. Consider using the {namespace}-{page} scheme for namespacing.

edited Aug 25 '20 at 17:01

answered Aug 07 '13 at 01:19

Kevin Cox

3,080
1
32
32

14

the lack of sub-pages makes Gollum and GitHub wiki by extension a crippled "wiki". – Nov 25 '15 at 16:20
Funnily enough, Gollum's github says (at least nowadays) "Pages may be organized into directories any way you choose." – Tonsic Nov 25 '21 at 17:44

score 16 · Answer 4 · answered Jan 14 '15 at 18:26

16

It's not the an ideal solution but the workaround would be to create a custom sidebar where you create a table of contents with links to your pages. I find this to be better than folders anyway because it allows you to have a link to a single page under multiple hierarchies.

answered Jan 14 '15 at 18:26

Thanh Nguyen

495
6
11

2

That is the approach I have taken, but it leaves a "Pages" part that is a huge mess of pages (over 60 in my project). – Jason Short Sep 14 '16 at 20:38
The Pages part is collapsed so it doesn't clutter the sidebar thankfully – pd12 Oct 05 '16 at 00:28

score 1 · Answer 5 · answered Jun 11 '14 at 13:24

1

Actually, there is still a limitation. Yes, you can add 1 level (so, 1 subfolder). But that's it! I refactored my whole documentation layout, creating multiple levels of subfolders for organisation, but that was a no-go.

sigh

I must say: I'm appalled by this Gollum thing. I'm surprised Github even picked it up.

answered Jun 11 '14 at 13:24

gjoris

1,731
2
17
22

2

I don't think this is correct. I was looking at one of the git recommended wiki sites, https://github.com/showcases/projects-with-great-wikis . I did a git clone and sure enough they have at least three levels of subdirectories. Take a look at the technical-documentation/1-trackers/ruby-tracker for example. – Ed Ost Aug 25 '14 at 03:40
ok, i tested it myself and it does seem that gollum has a problem with subdirectories that have the same name as even the link text. This is kind of wierd. I would understand if there was a collision in the actual page name, but when using mediaWiki syntax [[Link Text|WikiPage]] it does indeed seem to get confused between Link Text and actual directory name. – Ed Ost Aug 25 '14 at 04:46
This incredibly ugly and redundant format seems to works [PageName](PageName) – Ed Ost Aug 25 '14 at 05:03
1

gollum-lib does allow pagenames to have slashes, which behaves like you'd expect. Unfortunately, neither GitHub nor the "official" Sinatra-based Gollum frontend support these sensibly. – gerwitz Oct 14 '14 at 18:10
1

That github showcase in Ed Ost's comment no longer exists. An alternative fwiw https://www.quora.com/What-are-some-examples-of-very-well-made-GitHub-wiki-pages-for-open-source-projects – simesy Jul 26 '19 at 04:11

score 1 · Answer 6 · answered Sep 06 '22 at 20:36

1

Still no intention of adding this 9/2022.

https://github.com/orgs/community/discussions/23914

answered Sep 06 '22 at 20:36

abalter

9,663
17
90
145

March 2023: [Official GitHub Support answer](https://github.com/orgs/community/discussions/23914#discussioncomment-5447162): "no support, not on their roadmap". – VonC Mar 28 '23 at 08:15

score 0 · Answer 7 · answered Jul 20 '22 at 23:06

Well, that's a disappointing missing feature! What I try to do is to actually have directories under a docs directory and in each one, a README.md file. Not great...but works for documentation and organizes stuff. If you want to go further, you can have a different branch only with these files.

GitHub wiki directories

7 Answers7

Linked