How to structure GitHub wiki files?

Question

I have cloned one of my GitHub project's wiki locally, and I want to restructure the file system. By default different pages added to the wiki are all created in the parent directory:

/wiki
     home.md
     wiki_page_1.md
     ...

I want have a directory structure similar to this:

/wiki
  /setup
    setup_procedures.md
    index.md
  /development
    index.md
    tools.md
  /images
    front_page.png

I've tried to structure my wiki files similarly, but it's not working for the .md files. However, it works for the images folder. Is there a way to make this work?

For what it's worth, I've seen a team address this concern by dispensing with the Wiki proper and instead maintaining their .md files within the code repository. They created a Docs sub-folder (and folders) for .md files and a single designated sub-folder for all images and attachments, Wiki linking to them as needed. I wasn't crazy about the UX but, it seemed to work for them. — ScottWelker, Aug 01 '22 at 20:07

score 15 · Accepted Answer · edited Jun 20 '20 at 09:12

15

If GitHub is still using github/gollum, then, as explained in "How can you use subdirectories in a GitHub wiki checkout?", subfolders are not supported (or were buggy at the time of the fork).

More recent versions of gollum/gollum supports that organization, even though recent PR (Pull Requests) are still fixing issues around it (like PR 787).

The OP tsega adds in the comments:

tried to look into the Gollum wiki myself and it turns out you can organize your files under directories but that will not be how you access them.

Every page is accessed from the root of the wiki,e.g. github.com/user/repo/wiki/file-name not github.com/user/repo/wiki/directory/file-name.

The file names should be unique, and if you want to have proper titles they need to be capitalized and dashed (not underscored).

edited Jun 20 '20 at 09:12

Community

1
1

answered Jun 16 '14 at 05:34

VonC

1,262,500
529
4,410
5,250

Thanks @VonC for the answer, tried to look into the [Gollum wiki](https://github.com/gollum/gollum/wiki) myself and it turns out you can organize your files under directories but that will not be how you access them. Every page is accessed from the root of the wiki,e.g. `github.com/user/repo/wiki/file-name` not `github.com/user/repo/wiki/directory/file-name`. The file names should be unique, and if you want to have proper titles they need to be capitalized and dashed (not underscored). Thanks again for the help. – tsega Jun 16 '14 at 07:40
@tsega Ok. I have added your conclusion in the answer for more visibility. – VonC Jun 16 '14 at 07:42

score 1 · Answer 2 · answered Jul 05 '16 at 18:17

1

I've just hit the same problem and I've solved it (kinda) using a custom menu bar, and using regular Markdown, i.e. headers and links to create a folder structure.

answered Jul 05 '16 at 18:17

Felipe

11,557
7
56
103

Can you please send an example? – Noam Peled Mar 31 '17 at 17:12
2

@NoamPeled For example, [spring framwork](https://github.com/spring-projects/spring-framework/wiki) – niaomingjian Jun 13 '17 at 10:04
1

-1 because this doesn't actually handle page organization, it just combines pages. This is only practical for a low amount of content/pages. – Fuzzy Logic Aug 25 '18 at 00:22

score 1 · Answer 3 · answered Jul 28 '22 at 13:56

1

In 2022 this is still not possible.
Please upvote this feature request

answered Jul 28 '22 at 13:56

Floris Devreese

3,127
2
21
31

How to structure GitHub wiki files?

3 Answers3