How to Enable Directory Indexing on GitHub Pages

Question

I need to display directory contents on GH Pages.

Would prefer

Automatically, without index.html
A tool or library for automatically generating the index.html
Any other method

So, if I have a FS in my GH Pages repository:

http://github.com/[username]/[username].github.io/ :

script/
- app/
  - core/
    - init.js
- lib/
  - Element.animate.js
  - Object.overlay.js
- mod/
  - anim/
    - global/
      - carousel/
        - carousel.js
      - global.js
- ext/
  - cfgs.js
index.html

I would want each directory URL to index as usual, like so.

http://[username].github.io/script/ :

- app/
- lib/
- mod/
- ext/

http://[username].github.io/script/mod/anim/global/ :

- carousel/
- global.js

The only thing I can think of is preference #2, write or find a script to automatically generate the index.html from the GitHub Repo page or the local Repo on my FS.

score 35 · Answer 1 · edited Apr 27 '22 at 08:59

35

If you want a dynamic index that doesn't require any updating the only method I've found is by generating it client side with the github contents api.

Here is a simple example that creates links to files in the top level directory of your project. If you want to support subdirectories using this method you would have to recursively request the contents of each folder.

<html>
  <body>
    <script>
      (async () => {
        const response = await fetch('https://api.github.com/repos/:user/:repo/contents/');
        const data = await response.json();
        let htmlString = '<ul>';
        
        for (let file of data) {
          htmlString += `<li><a href="${file.path}">${file.name}</a></li>`;
        }

        htmlString += '</ul>';
        document.getElementsByTagName('body')[0].innerHTML = htmlString;
      })()
    </script>
  <body>
</html>

Here's an example where I used this to create a simple directory for a flat repo I have.

edited Apr 27 '22 at 08:59

Paul T. Rawkeen

3,994
3
35
51

answered Nov 09 '18 at 01:15

TimE

2,800
1
27
25

This might be a solution I am looking for. Do you know if this API support multi level (nested) folders. – rattanak Jun 17 '20 at 00:23
That is a great solution. I just created myself an image gallery index from this with a little bit uhtml magic. https://geolytix.github.io/MapIcons/ – Dennis Bauszus Sep 08 '20 at 17:22
[This](https://docs.github.com/v3/repos/contents/) is the new link to the docs! The suggested edit queue is full, thats why I put it here. – Timo Oct 07 '20 at 17:47
very useful thank you. small note that obvious for most but it took me few attempts to get it. remove the colon : when adding your username and repo name. eg `https://api.github.com/repos/myrepo/repo1/contents/` not `https://api.github.com/repos/:myrepo/:repo1/contents/` – Bahi8482 Jan 26 '23 at 21:09

Matthew Brett · Accepted Answer · 2020-05-23T13:20:09.307

I also wanted to do this. I tried uploading an .htaccess file with contents Options +Indexes to the relevant directory, but that did not work.

So, I used your option #2, writing a tiny Python script to generate an index file for the directory.

""" Build index from directory listing

make_index.py </path/to/directory> [--header <header text>]
"""

INDEX_TEMPLATE = r"""
<html>
<body>
<h2>${header}</h2>
<p>
% for name in names:
    <li><a href="${name}">${name}</a></li>
% endfor
</p>
</body>
</html>
"""

EXCLUDED = ['index.html']

import os
import argparse

# May need to do "pip install mako"
from mako.template import Template


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("directory")
    parser.add_argument("--header")
    args = parser.parse_args()
    fnames = [fname for fname in sorted(os.listdir(args.directory))
              if fname not in EXCLUDED]
    header = (args.header if args.header else os.path.basename(args.directory))
    print(Template(INDEX_TEMPLATE).render(names=fnames, header=header))


if __name__ == '__main__':
    main()

The idea is to create locally a list with the script, then copy the html to a html file and upload it to github. So for me the next step is to output the list to a html file and not print it to the terminal. — Timo, Oct 07 '20 at 17:32

score 7 · Answer 3 · answered Oct 27 '16 at 15:35

Better is this way which will go into subdirectory and make index files for them as well

""" Build index from directory listing

make_index.py </path/to/directory> [--header <header text>]
"""
from __future__ import print_function
import os.path, time

INDEX_TEMPLATE = r"""

<html>
<head>
<title>${header}</title>
<meta name="description" content="${header}"/>

</head>
<body>
    <h2>Index of ${header}</h2>
    <p>
    <table>
        <tbody>
            <tr>
                <th valign="top"><img src="${ROOTDIR}images/blank.gif"
                    alt="[ICO]"></th>
                <th><a href="?C=N;O=D">Name</a></th>
                <th><a href="?C=M;O=A">Last modified</a></th>
                <th><a href="?C=S;O=A">Size</a></th>
                <th><a href="?C=D;O=A">Description</a></th>
            </tr>
            <tr>
                <th colspan="5"><hr></th>
            </tr>
            <tr>
                <td valign="top"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAmlJREFUeNpsU0toU0EUPfPysx/tTxuDH9SCWhUDooIbd7oRUUTMouqi2iIoCO6lceHWhegy4EJFinWjrlQUpVm0IIoFpVDEIthm0dpikpf3ZuZ6Z94nrXhhMjM3c8895977BBHB2PznK8WPtDgyWH5q77cPH8PpdXuhpQT4ifR9u5sfJb1bmw6VivahATDrxcRZ2njfoaMv+2j7mLDn93MPiNRMvGbL18L9IpF8h9/TN+EYkMffSiOXJ5+hkD+PdqcLpICWHOHc2CC+LEyA/K+cKQMnlQHJX8wqYG3MAJy88Wa4OLDvEqAEOpJd0LxHIMdHBziowSwVlF8D6QaicK01krw/JynwcKoEwZczewroTvZirlKJs5CqQ5CG8pb57FnJUA0LYCXMX5fibd+p8LWDDemcPZbzQyjvH+Ki1TlIciElA7ghwLKV4kRZstt2sANWRjYTAGzuP2hXZFpJ/GsxgGJ0ox1aoFWsDXyyxqCs26+ydmagFN/rRjymJ1898bzGzmQE0HCZpmk5A0RFIv8Pn0WYPsiu6t/Rsj6PauVTwffTSzGAGZhUG2F06hEc9ibS7OPMNp6ErYFlKavo7MkhmTqCxZ/jwzGA9Hx82H2BZSw1NTN9Gx8ycHkajU/7M+jInsDC7DiaEmo1bNl1AMr9ASFgqVu9MCTIzoGUimXVAnnaN0PdBBDCCYbEtMk6wkpQwIG0sn0PQIUF4GsTwLSIFKNqF6DVrQq+IWVrQDxAYQC/1SsYOI4pOxKZrfifiUSbDUisif7XlpGIPufXd/uvdvZm760M0no1FZcnrzUdjw7au3vu/BVgAFLXeuTxhTXVAAAAAElFTkSuQmCC "
                    alt="[PARENTDIR]"></td>
                <td><a href="../">Parent Directory</a></td>
                <td>&nbsp;</td>
                <td align="right">-</td>
                <td>&nbsp;</td>
            </tr>
            <tr>
                <th colspan="5"><hr></th>
            </tr>

            % for name in dirnames:
            <tr>
                <td valign="top"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAd5JREFUeNqMU79rFUEQ/vbuodFEEkzAImBpkUabFP4ldpaJhZXYm/RiZWsv/hkWFglBUyTIgyAIIfgIRjHv3r39MePM7N3LcbxAFvZ2b2bn22/mm3XMjF+HL3YW7q28YSIw8mBKoBihhhgCsoORot9d3/ywg3YowMXwNde/PzGnk2vn6PitrT+/PGeNaecg4+qNY3D43vy16A5wDDd4Aqg/ngmrjl/GoN0U5V1QquHQG3q+TPDVhVwyBffcmQGJmSVfyZk7R3SngI4JKfwDJ2+05zIg8gbiereTZRHhJ5KCMOwDFLjhoBTn2g0ghagfKeIYJDPFyibJVBtTREwq60SpYvh5++PpwatHsxSm9QRLSQpEVSd7/TYJUb49TX7gztpjjEffnoVw66+Ytovs14Yp7HaKmUXeX9rKUoMoLNW3srqI5fWn8JejrVkK0QcrkFLOgS39yoKUQe292WJ1guUHG8K2o8K00oO1BTvXoW4yasclUTgZYJY9aFNfAThX5CZRmczAV52oAPoupHhWRIUUAOoyUIlYVaAa/VbLbyiZUiyFbjQFNwiZQSGl4IDy9sO5Wrty0QLKhdZPxmgGcDo8ejn+c/6eiK9poz15Kw7Dr/vN/z6W7q++091/AQYA5mZ8GYJ9K0AAAAAASUVORK5CYII= "
                    alt="[DIR]"></td>
                <td><a href="${name}">${name}</a></td>
                <td align="right">${time}</td>
                <td align="right">-</td>
                <td>&nbsp;</td>
            </tr>
            % endfor
            % for name in filenames:
            <tr>
                <td valign="top"><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAABnRSTlMAAAAAAABupgeRAAABHUlEQVR42o2RMW7DIBiF3498iHRJD5JKHurL+CRVBp+i2T16tTynF2gO0KSb5ZrBBl4HHDBuK/WXACH4eO9/CAAAbdvijzLGNE1TVZXfZuHg6XCAQESAZXbOKaXO57eiKG6ft9PrKQIkCQqFoIiQFBGlFIB5nvM8t9aOX2Nd18oDzjnPgCDpn/BH4zh2XZdlWVmWiUK4IgCBoFMUz9eP6zRN75cLgEQhcmTQIbl72O0f9865qLAAsURAAgKBJKEtgLXWvyjLuFsThCSstb8rBCaAQhDYWgIZ7myM+TUBjDHrHlZcbMYYk34cN0YSLcgS+wL0fe9TXDMbY33fR2AYBvyQ8L0Gk8MwREBrTfKe4TpTzwhArXWi8HI84h/1DfwI5mhxJamFAAAAAElFTkSuQmCC "
                    alt="[DIR]"></td>
                <td><a href="${name}">${name}</a></td>
                <td align="right">${time}</td>
                <td align="right">-</td>
                <td>&nbsp;</td>
            </tr>
            % endfor
            </p>
        </tbody>
    </table>
</body>
</html>
"""

EXCLUDED = ['index.html']

import os
import argparse

# May need to do "pip install mako"
from mako.template import Template

def fun(dir,rootdir):
    print('Processing: '+dir)
    filenames = [fname for fname in sorted(os.listdir(dir))
              if fname not in EXCLUDED and os.path.isfile(dir+fname)]
    dirnames = [fname for fname in sorted(os.listdir(dir))
            if fname not in EXCLUDED  ]
    dirnames = [fname for fname in dirnames if fname not in filenames]
#    header = os.path.basename(dir)
    f = open(dir+'/index.html','w')
    print(Template(INDEX_TEMPLATE).render(dirnames=dirnames,filenames=filenames, header=dir,ROOTDIR=rootdir,time=time.ctime(os.path.getctime(dir))),file=f)
    f.close()
    for subdir in dirnames:
        try:
            fun(dir+subdir+"/",rootdir+'../')
        except:
            pass

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("directory")
    parser.add_argument("--header")
    args = parser.parse_args()
    fun(args.directory+'/','../')

if __name__ == '__main__':
    main()

score 4 · Answer 4 · edited Jul 01 '19 at 09:09

4

I wrote a program for this.

See apindex.

edited Jul 01 '19 at 09:09

isopach

1,783
7
31
43

answered May 11 '18 at 20:58

Gala

2,592
3
25
33

score 0 · Answer 5 · answered Apr 27 '22 at 11:22

If your purpose is just to display the directory contents and you do not care much about how the overall page with the contents looks like, why not just giving to the consumers a link to the underlying repository folder?

In your case it would be something like https://github.io/[Repo name]/tree/master/[Folder name]

It will display a regular github files list view with a possibility to view and download each of them.

score 0 · Answer 6 · answered Apr 23 '23 at 05:40

2023 update: With Github actions you can do the site build remotely. https://github.com/marketplace/actions/github-pages-directory-listing which does just that. The author initially maintained a fork of @Gala's apindex, but later switched to this new code base.

How to Enable Directory Indexing on GitHub Pages

6 Answers6

Linked

Related