SimpleDir

Make archives and directory sites for free and easily.

Welcome

SimpleDir lets you create a directory-style website without writing an entire website from scratch. Add text, image slideshows, folders, and dividers to organize your content. I tried making this as stupidly simple as possible.

Use it for a personal page, a collection of links, a project index, a resource directory, or an archive.

The basic idea: The HTML template already handles the layout. You provide the entries in libraryData and leave the surrounding template code intact.

Getting started

  1. Open the SimpleDir repository on GitHub.
  2. Open the template HTML file.
  3. Scroll until you find the wall of red ❌ boundary comments.
  4. Write or paste your entries inside the libraryData object.
  5. Save your finished copy as index.html.
  6. Publish it with GitHub Pages or Vercel.
Keep const libraryData = {, its closing };, and the boundary comments. Only replace or add the directory entries in the designated area.

Text page

Create an entry that displays text.

{
    title: "About Me",
    type: "text",
    content: "Hello! Welcome to my website."
},

Change the title and content to your own.

Image page

The slideshow type can display an image. A single-slide slideshow can be used when you want one image in an entry. 

{
    title: "My Image",
    type: "slideshow",
    slides: [
        {
            image: "https://example.com/image.jpg"
        }
    ]
},

Replace the example URL with a URL to your image.

Text slideshow

Use multiple slides to show messages one at a time.

{
    title: "My Messages",
    type: "slideshow",
    slides: [
        { text: "Welcome!" },
        { text: "Thanks for visiting." },
        { text: "Have a great day!" }
    ]
},

Image slideshow

Use multiple images in a single slideshow.

{
    title: "My Photos",
    type: "slideshow",
    slides: [
        { image: "https://example.com/photo1.jpg" },
        { image: "https://example.com/photo2.jpg" },
        { image: "https://example.com/photo3.jpg" }
    ]
},

Mixed slideshow

A slide can contain text, an image, or both. This lets you combine captions and pictures in the same slideshow. 

{
    title: "My Collection",
    type: "slideshow",
    slides: [
        {
            text: "This is my first slide."
        },
        {
            image: "https://example.com/photo.jpg",
            text: "A photo with a caption."
        }
    ]
},

Folder

A folder groups other entries inside it.

{
    title: "My Folder",
    type: "folder",
    items: [
        {
            title: "First Page",
            type: "text",
            content: "This is inside the folder."
        },
        {
            title: "Second Page",
            type: "text",
            content: "This is another page."
        }
    ]
},

Nested folder

Folders can contain other folders.

{
    title: "Main Folder",
    type: "folder",
    items: [
        {
            title: "Subfolder",
            type: "folder",
            items: [
                {
                    title: "Inside the Subfolder",
                    type: "text",
                    content: "You found the nested page!"
                }
            ]
        }
    ]
},

Dividers

A divider is an entry in libraryData, rather than simply a line of HTML added outside the directory data. The template may use its content field when displaying the divider. 

{
    type: "divider",
    content: "My section divider"
},
Keep the divider's content field if it is present in your template's examples. Its precise display behavior depends on the template's rendering code.

Publish with GitHub Pages

GitHub Pages can host a static HTML website for free.

Step 1: Open the SimpleDir template

Open blankpage.html ↗ and copy it into your code editor.

Step 2: Find the red ❌ boundaries

Scroll through the file until you find the wall of red ❌ comments. They mark the part of the template intended for your code. It is easy to spot when scrolling fast. 

/* ❌❌❌ DO NOT EDIT ABOVE HERE!! ❌❌❌ */

const libraryData = {
    hi :D
};

/* ❌❌❌ DO NOT EDIT BELOW HERE!! ❌❌❌ */
Do not delete the const libraryData = { line, the closing };, or the boundary comments. Put your entries inside the braces.

Step 3: Add your entries

Copy an example from this documentation and place it inside libraryData. When adding several entries, separate them with commas as required by JavaScript.

Step 4: Save as index.html

Save your finished file as index.html. This is the standard entry filename for a basic static website.

Step 5: Create a repository

  1. Sign in to GitHub.
  2. Create a new repository for your website.
  3. Upload index.html to the repository's root folder.
  4. Commit the file.

Step 6: Enable GitHub Pages

  1. Open your website repository.
  2. Go to Settings.
  3. Choose Pages in the sidebar.
  4. Under the build and deployment options, choose deployment from a branch if prompted.
  5. Select the main branch and /(root).
  6. Click Save.

Step 7: Open your website

After GitHub Pages publishes the site, the Pages settings will show the published address. Open it to check your website.

If the website does not appear, check the filename, publishing folder, and JavaScript syntax.

Publish with Vercel

Vercel is another service that can host a static HTML website. Importing a GitHub repository is usually the easiest workflow.

Option A: Import from GitHub

  1. Save your website as index.html.
  2. Upload the file to a GitHub repository and commit it.
  3. Open Vercel.
  4. Choose the option to add a new project.
  5. Import your GitHub repository.
  6. Follow the project setup instructions.
  7. Deploy and open the URL Vercel provides.

Option B: Use a supported deployment workflow

  1. Make sure your file is named index.html.
  2. Check Vercel's current deployment options and documentation.
  3. Use a supported CLI or deployment workflow for the folder containing your HTML file.
  4. Open the deployed URL.
Vercel's dashboard options can change. Importing a GitHub repository is a good starting point if you are new to deployment.

Free custom domains and subdomains

You do not always need to pay for a domain to give your website a memorable address. Some providers offer free subdomains that you can connect to your published website.

Free subdomain examples

A subdomain such as yourname.devs.surf is provided under the parent domain devs.surf. You do not own the parent domain, and your continued use depends on the provider's terms and policies.

Step 1: Publish your website

Publish your SimpleDir site using GitHub Pages or Vercel first. Check that the platform-provided website address works.

Step 2: Register a free subdomain

Visit a provider that offers free subdomains, check whether your preferred name is available, and review its DNS options and terms.

Step 3: Add the domain to your hosting project

Open the custom-domain settings for your GitHub Pages or Vercel project and enter the subdomain you registered.

Step 4: Configure DNS

In the subdomain provider's DNS settings, add the records requested by your hosting service. The exact records depend on your hosting provider and domain configuration.

Step 5: Verify and test

Wait for the DNS changes to take effect, complete any domain verification steps, and test the new address. Enable HTTPS if your hosting provider offers it for the domain.

Free subdomain availability, renewal rules, DNS features, and permitted uses can change. Check the provider's current rules before relying on a free subdomain for a long-term project.

Do I need to buy a domain?

No. You can use the free address provided by GitHub Pages or Vercel, or connect a free subdomain if its provider supports your hosting setup. Buying your own domain is optional.

Important notes